Create Golang API Documentation with Swagger

1. Title – Short textual caption
2. Description – Textual description
3. Schemes – List of accepted schemes
4. BasePath – The default base path of the API (prefix to all routes)
5. Version – current API version
6. Contact – person to contact (name, email, and url)
7. Consumes – list of default mime types for the content the API receives
8. Produces – list of default mime types for the content the API sends
9. SecurityDefinitions – list of supported authorization types (Oauth, basic or apiKey)

Specifying the accepted schemes and consumption/production mime types on a global level allows us to omit them from the endpoints themselves. Nevertheless, variations in an endpoint can be specified differently, so the global value is overwritten.

When a SecurityDefinition is given, Swagger UI displays an extra button for authorization.

The resulting specification looks like this in Swagger UI:

Generate the Swagger Specification

Before we move on, let’s generate the Swagger specification file with

%GOPATH%/bin/go-swagger generate spec -o ./swagger.json

You can also create a yml file instead of json. For a full list of command options, go to https://goswagger.io/generate/spec.html.

Serve API Documentation Page

Go-swagger has a command to serve the generated json document:

%GOPATH%/bin/go-swagger serve ./swagger.json

This hosts the specification on your own machine and opens a new tab in your browser with Redoc (http://localhost:57396/docs).

Alternatively, add the -F=swagger parameter to host and open it in Swagger UI instead (http://petstore.swagger.io/).

%GOPATH%/bin/go-swagger serve -F swagger ./swagger.json

Document API Endpoints

Now that we have done the preliminary work, we can start documenting the endpoints of the API. For this, we will use the swagger:operation annotation.

I will explain the details using some concrete examples. I use Echo as my HTTP router, by the way.

Simple endpoint: Health

The first simple example is a health endpoint. It simply returns status code 204 in case the service is running.

// Health returns OK to indicate a running service
func (router *Router) Health(c echo.Context) error {
	return c.NoContent(http.StatusNoContent)
}

This endpoint is annotated as follows:

// swagger:operation GET /health general Health
// Check if the service is running.
// Returns 204 without content
// ---
// responses:
//     '204':
//         description: Service available
router.echo.GET("/health", router.Health)

Here, we have a GET endpoint which can be called at <basepath>/health.

It has a title (second line – sentence must end with a dot) and description (third line). After --- the response type is defined with its status code and a mandatory description.

Complex endpoint: Authentication

The second endpoint expects the user’s username and password and returns an Oauth2 token to the user.

// swagger:operation POST /oauth/token auth GetToken
// Authenticate and authorise with Windows credentials.
// ---
// produces:
// - application/json
// parameters:
// - name: grant_type
//   in: formData
//   description: Grant type
//   required: true
//   type: string
//   default: "password"
// - name: username
//   in: formData
//   description: domain\username
//   type: string
//   required: true
// - name: password
//   in: formData
//   description: Your password
//   required: true
//   type: string
//   format: password
// responses:
//     '200':
//         description: Authenticated
//     '400':
//         description: Bad request
//     '500':
//         description: Internal server error
router.echo.POST("/oauth/token", auth.login)