[Golang] – How to generate swagger API doc from the source code

This post will explain how to do generated the documentation to be checked dynamically with the SwaggerUI and the package https://github.com/go-swagger/go-swagger which is using the OpenAPI.

Understanding how the SwaggerUI works

The SwaggerUI will parse a YAML file with the REST endpoint definitions and render it in UI where is possible to check it definitions and test these endpoints. Click here and test its demo.

Swagger API from the source code

In the reality is required to add comments on top of the router implemented in the source which will be used to generated by a command line the swagger.YAML file which is what actually is responsible to make the swasggerUI works.  Following the steps to do it in a Golang application.

• Installing swagger

The following command should get the package for your go project. However, check here all the options to install it.

$ go get -u github.com/go-swagger/go-swagger/cmd/swagger

• Adding swagger in the project

All go applications require the main implementation which will be called to run the program/server. It is the place where we will define the swagger API with its specs.

// API REST EXAMPLE
//
// This is a example over how to create the api from the source.
//
//     Schemes: http, https
//     Host: localhost:3000
//     Version: 0.1.0
//     basePath: /api
//
//     Consumes:
//     - application/json
//
//     Produces:
//     - application/json
//
// swagger:meta
package main

• Adding the comments/spec in the endpoints

For each router created implemented in your project you will add the swagger specs as comments on top of it.

   // swagger:operation GET /users users
   //
   // ---
   // produces:
   // - application/json
   // responses:
   //   '200':
   //     description: successful operation
   r.GET("/users", usersHandler.GetUsers)

• Running the command line to generate the swagger.YAML file 

Go to the directory where is the main.go file and execute the following command.  The swagger.yaml will be generated in the root dir of the project.

swagger generate spec -m -o ../../swagger.yaml

NOTE: In the above example the main.go file is not in the root of the project.

Now, you have the swagger.YAML file and you can use it in the swaggerUI :-). You can test the file created in the Swagger demo.

TIPS – Swagger schema to be used in the source code.

Following here a few examples in order to help you with it.

A more complex router definition

// swagger:operation GET /users/{id} User
//
// add here the decsription 
// ---
// summary: Get user by id
// operationId: getUserById
// produces:
// - application/json
// parameters:
// - name: id
//   in: path
//   description: The id for the user that needs to be fetched.
//   required: true
//   type: string
// responses:
//   200:
//     description: successful operation
//     schema:
//       $ref: '#/definitions/User'
//   400:
//     description: Invalid id supplied
//   404:
//     description: User not found
r.GET("/users/{id}", appsHandler.GetUserById)

Model definition

package models

// Description of the Model
// swagger:model User
type User struct {
   ID                    string    `json:"id"`
   Name                  string    `json:"name"`
}