Generate swagger specification from Go source code

If you have some API written in Go for which you want to generate some fancy swagger specification, well this article is just about that!

Why swagger?

We developers usually don’t enjoy that documentation part in our jobs that much. It looks boring, repetitive and not that enjoyable. However documentation is a “must” for any API. Here is why:

So documentation is good but simply writing some markdown file is most of the time not enough. We want a tool that is standardized for the job, easy to share and descriptive enough. Well Swagger is the first such tool that comes to mind. It is kind of a de facto standard for documenting APIs.

Why not just write it by hand?

As developers we automate things. Well it feels natural to automate our own jobs as well, then.

Swagger docs are nice. For having one, all you need to do is to write a json or yaml file describing your API in term of URLs, requests and responses with a specific syntax. Then you will pass that specification to some other tool like swagger editor which will generate some amazing html and css out of it. In the following image you can see the specification on the left and the resulting documentation on the right:

Here’s what we gain by automating creation of swagger specification:

Comparison of two tools for generating the spec

So how can I generate that spec?

I will go through a case study describing how you can use go-swagger to generate your swagger specification. But before we start please note that in order for go-swagger to work, your package should be located correctly under GOPATH (even if you use go modules) and you should have a vendor folder containing your dependencies. I will describe this in more detail later.

Well… first you need to have an API. Here is a simple API that takes a POST request and returns a response. Bodies of both requests and response are JSON.

Then we will create a separate package to hold the comments and structs written for the purpose of Swagger. We will name it docs . But before that in our main file main.go we need to add an import for our docs package. This is because without that import, the docs package is not imported anywhere in the code, therefore it will be ignored during the build. go-swagger starts looking for packages from main.go and follows is imports recursively. Therefore without such import there will be no docs for us! In our main file we also set up basic auth for all our endpoints.

So now that we have a simple application up and running we can go for the docs package and see what should go in there. In order to give general information about our APIs as a whole (not any endpoint in specific) we need to create a file in our docs package and add a package comment like this:

Finally we document the foobar endpoint under docs package using just a few lines of comments and go code. Here is how it looks like:

A few things to point out about this snippet are:

This is the docs that get generated for this specific endpoint:

What commands do I need?

First I should emphasize that you need to put your project under GOPATH properly.

If you already use vendor package, you are good to go, otherwise if you are using go modules run the following command to create one: GO111MODULE=on go mod vendor

Then go on and install go-swagger via:

Finally to generate swagger specification and putting it in a file called swagger.yaml you need to run GO111MODULE=off swagger generate spec -o ./swagger.yaml --scan-models in the root of project.

To see the resulting documentation. (viewing the yaml file as a fancy webpage) you can run: swagger serve -F=swagger swagger.yaml

If the commands look complicated there’s a simpler way! Just create a file called Makefile in the root of your project and paste the following snippet into it:

Source code and go-swagger docs

Related posts:

JTC Trades Jobs of OKC provides employment opportunities with career advancement training on the the job! OKC Job searching can be tedious, but JTC makes the job of getting hired a breeze! Our…

De que el domingo pese a que pase hay una letra de (in)diferencia y un olvido de por medio.. “Todo cambia” is published by IB.

The Digital Technology Platform for The Future. Bitcoin Red Diamond is a peer-to-peer crypto currency and can be termed as a modified version of the technology on which bitcoin was built. The main…