Generate RESTful API Documentation From Annotations in Go code

Hello! Colm Murphy and I (Robert 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 theswagger 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.

// @APIVersion 1.0.0
// @APITitle Teamwork Desk
// @APIDescription Bend Teamwork Desk to your will using these read and write endpoints
// @Contact support@teamwork.com
// @TermsOfServiceUrl https://www.teamwork.com/termsofservice
// @License BSD
// @LicenseUrl http://opensource.org/licenses/BSD-2-Clause

2. Sub API Definitions (One per Resource)

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

// @SubApi User  [/users]
// @SubApi Allows you access to different features of the users , login , get status etc [/users]

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:

// @Title Get Users Information
// @Description Get Users Information
// @Accept json
// @Param userId path int true "User ID"
// @Success 200 {object} string "Success"
// @Failure 401 {object} string "Access denied"
// @Failure 404 {object} string "Not Found"
// @Resource /users
// @Router /v1/users/:userId.json [get]

4. Struct Tags

type User struct {  
    Id                *string   `required json:"id"`
    FirstName     *string   `json:"firstName,required" description:"The first's first/middle name(s)"`
    LastName      *string   `json:"lastName,required" description:"The users's last name (sorted by)"`
    userphoto *string   `json:"-"`
    contact            *Contact  `json:"contact,omitempty"`
}

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:

./$GOPATH/bin/api-documentation-generator -apiPackage=location to controller folders -mainApiFile=location to main.go file-basePath=https://{{installation}}.teamwork.com/desk

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.

• Checkout the Swagger in Go repo
• Checkout the new Teamwork Desk API Docs