Quick Start Guide

Quick Start Guide

1. Add comments to your API source code see Declarative Comments Format

2. Download Swagger for Go by using go get github.com/yvasiyarov/swagger.git

3. Compile the Swagger generator. go install

   This will create a binary in your $GOPATH/bin folder called swagger (Mac/Unix) or swagger.exe (Windows).

4. Run the Swagger generator. Be in the folder with your annotated API source code and run the swagger binary:

   ./$GOPATH/bin/swagger -apiPackage="my_cool_api" -mainApiFile="my_cool_api/web/main.go"

   Command line switches are:

   • -apiPackage - package with API controllers implementation
   • -mainApiFile - main API file. We will look for "General API info" in this file. If the mainApiFile command-line switch is left blank, then main.go is assumed (in the location specified by apiPackage).
   • -format - One of: go|swagger|asciidoc|markdown|confluence. Default is -format="go". See below.
   • -output - Output specification. Default varies according to -format. See below.
   • -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.

   You can output in different Formats, Please see below

5. 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

6. Enjoy it :-)