How to integrate swagger ui with golang and goa

Question

I have been building my first RESTful service with go and goa, so basically I started doing this and at the end, goa generate two swagger files, swagger.yaml and swagger.json. The thing is that I've been looking for a way to add the swagger ui to, let's say, the index. But I haven't been able to find an example for that.

I also look in the examples and in the design - swagger section but the only suggestion that they gave me is to use the goa swagger design generator, but I don't know if there's a way to perform this action without the need of accessing a public host?

Answer 1

TL;DR

The files example shows how to build an API that serves static assets, which can be adapted to including Swager-UI.

In order to follow the example:

1. Get the dependencies
2. Add Resources to the design.go file
3. Mount controllers in the main.go
4. Download and edit Swagger-UI
5. Run the generators

After this you should have a working REST-API including the Swagger-UI

Details

^{(Please replace example.com/your-package/ with the path to your package).}

1. Get the dependencies

In order to serve files, the example uses:

• go-bindata
  ^{Small utility which generates Go code from any file. Useful for embedding binary data in a Go program.}

• go-bindata-assetfs
  ^{Serves embedded files from go-bindata with net/http.}

Get these using:

go get github.com/a-urth/go-bindata/...
go get github.com/elazarl/go-bindata-assetfs/...

2. Add Resources to the design.go file:

    var _ = Resource("schema", func() {
        Files("/schema/*filepath", "public/schema/")
    })

    var _ = Resource("swagger", func() {
        Files("/swagger/*filepath", "public/swagger/")
    })

3. Mount controllers in the main.go

import (
    "net/http"

    "example.com/your-package/app"
    "example.com/your-package/public/swagger"

    "github.com/elazarl/go-bindata-assetfs"
    "github.com/goadesign/goa"
    "github.com/goadesign/goa/middleware"
)

func main() {
    // ...

    // Mount "schema" controller
    c1 := NewSchemaController(service)
    app.MountSchemaController(service, c1)
    // Mount "swagger" controller
    c2 := NewSwaggerController(service)
    // You can override FileSystem of the controller.
    // For example using github.com/elazarl/go-bindata-assetfs is like below.
    c2.FileSystem = func(dir string) http.FileSystem {
        return &assetfs.AssetFS{
            Asset:     swagger.Asset,
            AssetDir:  swagger.AssetDir,
            AssetInfo: swagger.AssetInfo,
            Prefix:    dir,
        }
    }
    app.MountSwaggerController(service, c2)

    // ...
}

4. Download Swagger-UI

Use your favorite method to download the dist folder of Swagger UI. Place all the files in the example.com/your-package/public/swagger folder.

In the example.com/your-package/public/swagger/index.html file:

• Search for http://petstore.swagger.io/v2/swagger.json
• Replace it with ./swagger.json.
  ^{That way the generated swagger.json will be used instead of the Petstore example.}

5. Run the generators

go generate goagen -d example.com/your-package/design app
go generate goagen -d example.com/your-package/design main
go generate goagen -d example.com/your-package/design swagger -o public
go generate goagen -d example.com/your-package/design schema -o public
go generate go-bindata -ignore 'bindata.go' -pkg swagger -o public/swagger/bindata.go ./public/swagger/...

This will create the controllers, swagger, schema and static content.

Done

You should now have a fully functional Swagger UI.

Answer 2

I was running this recently and also wondered how to get the swagger ui up. Once you've generated the openapi3.json files, you can use this docker-compose config to bring up the swagger ui. You can replace the mounted volume and the SWAGGER_JSON variable according to where the files are. Swagger ui should run okay in http://localhost:8080.

Note: You might need to enable CORS in goa to execute the requests.

swagger:
  image: swaggerapi/swagger-ui
  ports:
    - '8080:8080'
  environment:
    SWAGGER_JSON: '/openapi3.json'
  volumes:
    - ./gen/http/openapi3.json:/openapi3.json