swagger

command module
v0.0.0-...-9a64e21 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Jun 27, 2018 License: BSD-3-Clause Imports: 3 Imported by: 0

README

alt text

Swagger UI Generator for Go

About

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.


Project Status : Alpha
Declarative Comments Format : Read more
Technical Notes : Read More
Known Limitations : Read More

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

  3. Or, compile the Swagger generator from sources. 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 Generate different formats


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

  2. Enjoy it :-)

Documentation

The Go Gopher

There is no documentation for this package.

Directories

Path Synopsis
@SubApi Order management API [/orders]
@SubApi Order management API [/orders]
web
@APIVersion 1.0.0 @APITitle Swagger Example API @APIDescription Swagger Example API @Contact varyous@gmail.com @TermsOfServiceUrl http://yvasiyarov.com/ @License BSD @LicenseUrl http://yvasiyarov.com/
@APIVersion 1.0.0 @APITitle Swagger Example API @APIDescription Swagger Example API @Contact varyous@gmail.com @TermsOfServiceUrl http://yvasiyarov.com/ @License BSD @LicenseUrl http://yvasiyarov.com/

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL