Documenting Golang API using goswagger

Hi Learners, have tried documenting my learning on specification documentation generation for golang API using goswagger and hope it remains a useful read for your time. Lets get started.

First lets understand about some of the jargon terms mentioned in this document before going any further,

What is an API? (as chatGPT puts it😅)
API stands for “Application Programming Interface”. It’s a set of rules and protocols that define how different software applications should communicate with each other. API’s role in software application is similar to a waiter in restaurant. It takes requests from one software application (the “client”) and communicates those requests to another software application (the “server”). The server then processes the request and sends a response back to the client through the API. This allows different software applications to work together seamlessly, even if they were built by different developers or are running on different platforms

What is Goswagger?
Goswagger is the implementation of Swagger 2.0 (aka OpenAPI 2.0 or swagger specification or OpenAPI specification). OpenAPI Specification in simple terms is a format to describe our API’s. There are then various tools that are build upon based on these format that help us with things like client and server code generation for our API, UI to visualize our API, etc,. Goswagger is essentially one of those tools that is specifically build for golang language. (you can read on this article to get further understanding on OpenAPI)

Whats in this Article?
With above terms clarified lets understand what we are going to do in this article. The key advantage that OpenAPI specification and tools build around it provides is the generation of client and server code from the specification documentation which is in .json or .yaml format. This helps us to generate code for common tasks like coding the handler or controller part with all the required parameter parsings and validations and lets us to focus only on the service layer where our business logic resides. Also these code generation tools adhere to standard coding practices when generating the code.
But we also encounter the reverse scenario where we already have an API service running with server codes implemented by ourself and now need to generate the specification documentation for the same to share with others. We will learn about how to do this for an API service written in golang.

We will be documenting the API’s of this golang application which provide CRUD functionality on pet details.
Before going forward please install the go-swagger binary by following the instructions specified here.

Go-swagger recommends on structuring our documentation specific code in to separate package. Hence we have created a package named docs in the root directory of our project.

The docs.go file under the docs module contains some meta info about our application that goswagger will use when displaying the specification. We specify details like version of swagger, title description and version of our application, the schemes supported by our application etc. The // swagger:meta comment specifies to the generation tool that this is the meta data about the application.

Then we can start documenting our endpoints. Lets see how to document the AddPet endpoint.

We have specified the documentation for the add pet endpoint in the AddPet handler. Lets understand it going through each line.

// swagger:route POST /pets Pet AddPet
* The tag swagger:route denotes that the proceeding is a documentation for an endpoint.
* It is followed by the method of the endpoint (POST in this case).
* Then we have given the relative path for the endpoint( /pet in this case). * Then we have specified the group to which this endpoint belongs to( Pet in this case). This is used to group related endpoints under same section in the UI.
* Then it is followed by the name of the endpoint( AddPet in this case).

// add a new pet detail
This line is the description for the endpoint.

// responses:
// 500: ErrorResponse
// 200: SuccessRespWithoutData
Here we have mentioned the response returned by this endpoint on success and different error scenarios. As you can see we have only provided the name of the response schema here, the actually definition for these schemas are defined in the models.go file of docs package. Lets have a look at them.

The first line in the comment is a simple description for the schema. The tag swagger:response denotes that this schema is for response payload and is followed by the name of the response schema which is used to reference it in the endpoint documentations. The tag // in:body denotes that those fields will be present in the response body.

In the above definition we have mentioned the method, path, response and few meta infos like name and group of the add pet endpoint. The only detail missing about the endpoint is the request payload that the endpoint accepts. The schema for this is also defined in the models.go file of the docs package.

Again the first line of the comment is the description for the schema. The swagger:parameters tag specifies that this schema is for a parameter payload. It the followed by the name of the endpoint which uses this as a request parameter ( AddPet in this case). Please note that we haven’t specified any reference for its parameter while documenting the AddPet handler, rather we tie a parameter to an endpoint by specifying its name here. If the same request payload schema is used by multiple endpoints then we can specify it by giving the names of all those endpoint separated by space.

(Note :- the comments specified for the swagger specification are parsed as yaml formats by the tool, so please be consistent in your spacing)

That is it we have now provided the required details that goswagger needs to generate the specification for our AddPet endpoint.(Please refer the repo to have a look at how update, get and delete pet endpoints are documented). Now lets tell our goswagger tool to generate a beautiful specification for our endpoints by running the below command
`swagger generate spec -w cmd/ -o docs/swagger.json`
This command generates and writes our specification into docs/swagger.json file.

We can also view this documentation locally with the below cmd
`swagger serve -F=swagger docs/swagger.json`.
Goswagger documentation server will serve this beautiful documentation

The swagger serve tool will help with generating and serving this html in local environment only. But ideally we will need to server this documentation for our clients over an endpoint in production environment. The openapi’s runtime package provides us the middleware to generate the html from our json spec and serve it to our clients from our code.

(Note:- please make sure the path provided in the RedocOpts and the path under which the specification is served are the same as the redoc middleware has a check for it)

We can now get our specification served by visiting the url http://localhost:9000/docs

That is it for this article. I hope this blog helped you in understanding how to generate swagger specification doc for golang application.

Thanks for your time reading. Happy learning and sharing.