This is a utility for automatically generating API documentation from annotations in Go code. It generates the documentation as JSON, according to the Swagger Spec, and then displays it using Swagger UI.
This tool was inspired by Beego, and follows the same annotation standards set by Beego. The main difference between this tool and Beego is that this generator doesn't depend on the Beego framework. You can use any framework to implement your API (or don't use a framework at all). You just add declarative comments to your API controllers, then run this generator and your documentation is ready! For an example of what such documentation looks like when presented via Swagger UI, see the Swagger pet store example.
This tool focuses on documentation generation as opposed to client generation. If that is all you need, it will be significantly easier to integrate this tool into your existing codebase/workflow as opposed to goswagger. One significant advantage of this tool is that it allows you to easily reference objects that are outside of your package.
This tool currently generates Swagger 1.x spec files -- there are plans to update the tool to support Swagger 2.x at some point.
-
Add comments to your API source code, see Declarative Comments Format
-
Download Swagger for Go by using
go get github.com/yvasiyarov/swagger -
Or, compile the Swagger generator from sources.
go installThis will create a binary in your $GOPATH/bin folder called swagger (Mac/Unix) or swagger.exe (Windows).
-
Run the Swagger generator. Make sure to specify the full package name and an optional entry point (if the entry point isn't
$pkg/main.go).Example:
$ pwd /Users/dselans/Code/go/src/github.com/yvasiyarov/swagger $ ./$GOPATH/bin/swagger -apiPackage="github.com/yvasiyarov/swagger/example" -mainApiFile=example/web/main.go -output=./API.md -format=markdown
| Switch | Description |
|---|---|
| -apiPackage | Package with API controllers implementation |
| -mainApiFile | Main API file. This file is used for generating the "General API Info" bits. If -mainApiFile is not specified, then $apiPackage/main.go is assumed. |
| -format | One of: go|swagger|asciidoc|markdown|confluence. Default is -format="go". See See docs. |
| -output | Output specification. Default varies according to -format. See docs. |
| controllerClass | Speed up parsing by specifying which receiver objects have the controller methods. The default is to search all methods. The argument can be a regular expression. For example, -controllerClass="(Context|Controller)$" means the receiver name must end in Context or Controller. |
| contentsTable | Whether to generate Table of Contents; default: true. |
| models | Generate 'Models' section; default true. |
| vendoringPath | Override default vendor directory (eg. $CWD/vendor and $GOPATH/src/$apiPackage/vendor) |
| disableVendoring | Disable vendor usage altogether |
| enableDebug | Enable debug log output |
To run the generated swagger UI (assuming you used -format="go"), copy/move the generated docs.go file to a new folder under GOPATH/src. Also bring in the web.go-example file, renaming it to web.go. Then: go run web.go docs.go
Project Status : Alpha
Declarative Comments Format : Read more
Technical Notes : Read More
Known Limitations : Read More
Generating Different Format Docs: Read More