divan / buffalo-swagger

Buffalo middleware to automatically generate RESTful API documentation with Swagger 2.0.

buffalo-swagger

Buffalo middleware to automatically generate RESTful API documentation with Swagger 2.0.

Usage

Start using it

1. Add comments to your API source code, See Declarative Comments Format.
2. Download Swag for Go by using:

$ go get github.com/swaggo/swag/cmd/swag

3. The General API annotation lives in actions/app.go, run Swag in your Buffalo project root folder with the flag -g actions/app.go. Swag will parse comments and generate required files(docs folder and docs/doc.go).

$ swag init -g actions/app.go

4.Download buffalo-swagger by using:

$ go get -u github.com/swaggo/buffalo-swagger

And import following in your actions/app.go code, making sure to modify the last package name properly:

import(
    buffaloSwagger "github.com/swaggo/buffalo-swagger"
    "github.com/swaggo/buffalo-swagger/swaggerFiles"
    _ "github.com/<github_name>/<project_name>/docs"
)

Canonical example:

For a complete example take a look at the example directory Below you can find an extract from actions/app.go

package actions

import(
    buffaloSwagger "github.com/swaggo/buffalo-swagger"
    "github.com/swaggo/buffalo-swagger/swaggerFiles"
    _ "github.com/swaggo/buffalo-swagger/example/docs"
)

[...]
var app *buffalo.App

// @title Swagger Example API
// @version 1.0
// @description This is a sample server Petstore server.
// @termsOfService http://swagger.io/terms/

// @contact.name API Support
// @contact.url http://www.swagger.io/support
// @contact.email [e-mail]

// @license.name Apache 2.0
// @license.url http://www.apache.org/licenses/LICENSE-2.0.html

// @host petstore.swagger.io
// @BasePath /v2
func App() *buffalo.App {
    if app == nil {
        app = buffalo.New(buffalo.Options{
            Env:          ENV,
            SessionStore: sessions.Null{},
            PreWares: []buffalo.PreWare{
                    cors.Default().Handler,
            },
            SessionName: "_example_session",
        })
    app.GET("/", HomeHandler)
    app.GET("/swagger/{doc:.*}", buffaloSwagger.WrapHandler(swaggerFiles.Handler))

}

return app

5. Run it, and browse to http://localhost:3000/swagger/index.html, you can see Swagger 2.0 Api documents.