Generate RESTful API Documentation From Annotations in Go code

Posted

Hello! Colm Murphy and I (Robert James Gabriel) are both interns here at Teamwork.com. We were given the task by Peter Coppinger and Teamwork Desk Product Lead Brandon Hansen , to create an API documentation generator for Teamwork Desk. This is so that you wonderful people can get your teeth into Teamwork Desk’s API. What does that mean? Well, we want to be able to create our API documentation with just the code. Changes to the code should, and hopefully will, be reflected in the generated documentation.

Why bother?

On this world wide web of ours, APIs make it possible for programs like Teamwork Projects, Teamwork Desk, and Teamwork Chat to allow other applications to piggyback on our services. This is how certain apps display information on Google maps within their own applications. An API accomplishes all of this business by revealing some of a program’s internal functions to the wider world in a restricted fashion. This is how Teamwork.com and others share data with other applications. It’s a means of working together, without sharing all of the software’s code. This is where documentation becomes super-important.

With this in mind, it became apparent that a more efficient and cleaner system was required to generate the API documentation automatically.

The Challenge

The main challenge was to find or build a system that could work with the Revel framework and could be easily implemented.It was important to release our public API as soon as possible, as it’s a common request received by our support teams.

We needed to bolt on a repository or two that could work with the current version of Teamwork Desk (Revel framework) to generate API documentation automatically.
There were quite a few to test – and test we did – until a repository was found that, with a little adapting, could support auto-documentation.

Problems

The biggest issue that we ran into when researching different methods and approaches, was that no built-in API documentation generator exists with the Revel framework, although future versions might possibly will have this feature.
We could have built our own solution that, in theory, could read through our code and generate the documentation required. But using an open source method allows for better development and bug fixes.

Solution

Software engineering 101 states, “do not reinvent the wheel!” We discovered a great repository called Swagger UI Generator for Go that employs a version of SWAGGER to achieve much of what we required, but had a few problems. This repository is a utility for automatically generating API documentation from unique annotations in Go code. It can generate the documentation as a JSON array and according to the swagger specifications (1.2), display it using the Swagger UI.

How it works? Its split into four steps.

1. General API info

In the main file, add the following comments to the “main” file of your application, above the “package” keyword. The purpose of each annotation should be self-explanatory.

2. Sub API Definitions (One per Resource)

The next part is the sub APIs, you can read about the differently in this here. So, for any sub API, example user sub API http://developer.teamwork.com/v1/users/, we added the following annotation to the top of the file.

3. API Operation

The most important annotation comments for swagger UI generation are these comments that describe an operation (GET, PUT, POST, etc.). These comments are placed within your controller source code. One full set of these comments is used for each operation. They are placed just above the code which handles that operation.

Example:

4. Struct Tags

How it works is the frameless version of Swagger will read the code for comments and generator either a JSON file, XML, or even a docs.go file. That way the SWAGGER-UI then creates an interactive UI for people to test it out.

After that, you simply run the following command:

Problems/Fixes

Because the Swagger in Go repository is in an alpha stage, there was some problems we encountered. As an example, I rewrote the web.go file to allow HTTP access control (CORS). As we can make the call from without the port.

We also wrote a script to enable the updating of the Docs by the click of a button, which will gently shut down the generator and rebuild the docs.

Other problems that arose were the lack of support for array lists.

So, I have been onto the creator of Swagger in Go to update the system to Swagger 2.0 which allows for more support. I’m currently writing this to be pushed over later in the year with others in the community, it will follow the Swagger 2.0 spec.

Other areas I created include the feature to allow two packages from different locations to be read and generated into the docs. This will be pushed over later too into the Public repo.

Updated the UI of Swagger UI to Bootstrap 3.0 and allowed a feature to update the docs from an URL.

It’s also noted this can be used with other programming languages as well and not just Golang.

I hope you found this useful.

As you can see with the changes we have made and the repository itself it’s really easy to set up a API Documentation with Swagger.

If you have any questions, just let us know below and I hope people find this useful in how to create a API docs by just adding a few comments.

  • Matthew Armstrong

    I’m in the same boat, personally. Would be nice to get a swagger URL for the TWD API. 🙂