As you may know we’ve recently been trying to improve how we write and display our developer documentation. We’ve done lots of user research with technical architects, developers and service managers so we have an idea of what good documentation looks like. One of the biggest challenges though is finding the right tools that can create our picture of good.
On GOV.UK Pay, we assessed a number of tools that had the potential to create this picture, including Swagger, Swagger UI, RAML, API Blueprint, Slate, Aglio and Gelato. This post will explain why we made certain decisions before choosing our current documentation tools. Bear in mind this is very much a work in progress and we’re still considering alternatives.
Automating our documentation
We looked at Swagger to automate our documentation. Swagger helps us ensure documentation is up to date by using code annotations to produce API endpoint reference documentation. This reassures government developers who are often concerned their reference material is outdated.
We integrated Swagger with our API using Java annotations on our resource endpoints. Typically, Swagger dynamically generates the documentation in a JSON format at runtime, but this would involve us exposing resource endpoints, leaving us open to security vulnerabilities.
Instead we decided to generate the documentation at compilation time (while we were actually writing the code) using a Swagger library. This means every change we make to the code gives us a new JSON file.
We used a plugin called Swagger Maven to produce the Swagger JSON with every Maven compilation phase (Maven is a build automation tool), ensuring we have a really well documented API. Although Swagger annotations could infer quite a fair amount of knowledge about our endpoints, we still had to create some plain old Java object (POJO) to assist Swagger’s understanding of the HTTP Request and Response types.
You can see our use of Swagger annotations in our public repo now on Github.
Providing our documentation with a nice design
After deciding we liked the output from Swagger, we still needed a tool that would consume the Swagger JSON file and provide our documentation with a nice design and layout, ensuring the content appealed to developers.
Since companies like Stripe, GoCardless and Spotify, were frequently referenced by users as having accessible documentation, we decided to try and mimic them by using a tool called Slate. Our initial plan was to integrate the Swagger API with Slate through a JSON/YAML file to provide a UI that has three columns and consists of an index, content and code examples.
Because Slate only consumes Markdown files, we had to first convert our Swagger JSON file to a Markdown file and we tried to use a GitHub project to do this. Unfortunately the documentation and the executable failed to convert the JSON file. There are other downsides of Slate and I’ll go into these shortly.
We put use of Slate on hold and had a look for alternatives. Swagger UI dynamically generates documentation and a sandbox from a Swagger-compliant API. The tool has no dependencies and we could host it in any server environment or on our local machine. Swagger UI was fairly simple to setup and there were no problems rendering our Swagger JSON file.
The advantage of Swagger UI is the sandbox functionality, which would allow developers to test their interaction with our public API. The disadvantages of the tool were that it lacked certain sections for content (like an overview section) and code examples. Both of these aren’t too crucial (although desired by users) and we may consider using Swagger UI in the future, but during this initial testing of documentation tools we wanted to find something that ticked all our boxes.
We decided to test the combination of API Blueprint and Aglio. API Blueprint, like Swagger, is an API specification format and is Markdown-based so you can write API descriptions and documentation in a simple and straightforward way. Aglio outputs static HTML from the API Blueprint file, which can be served from any webhost and supports multiple themes.
The installation of Aglio was fairly straightforward. Although we couldn’t use our Swagger file (as the file wasn’t in Markdown), we could use our internal README.md. Aglio has a Slate theme, which produces output in three columns. An online example can be found here.
Both Aglio and Slate are problematic in that we’d have to keep manually updating files and they both lack sandbox functionality, which our developers are very keen on having.
These downsides, together with the fact that API Blueprint has a much smaller community than Swagger, meant that we decided to look at another tool called Gelato.
We stumbled upon Gelato while looking for alternatives and found that it could sync or import both Swagger and API Blueprint files. It has clear benefits in that it:
- can generate sample code in 6 different programming languages
- can present information clearly on response parameters (not just request ones)
- has an interactive document editor
- has an API Explorer (sandbox functionality)
It was really easy to import our existing Swagger file into Gelato, and Gelato was actually able to infer more things from our Swagger file than Swagger UI. We decided to host our GOV.UK Pay documentation with Gelato for the time being because it ticks all our users’ boxes.
Of course, RAML is another popular API documentation tool and this was on our radar, however we felt it was more suited to waterfall design patterns rather than the agile environment we work in (since it tends to foster a design-first approach).
Next steps
Having been successful at an alpha stage with Gelato, we’re now looking at what we’ll do through Beta. We’re currently considering our options, which range from continuing to use a hosted solution through to creating our own API documentation tool or modifying another tool available from the market. Since we’re happy with Swagger and the output its generating, we’re mainly considering tools that can work with it. We’re also user testing Swaggerly, an open source API documentation tool recently released by Companies House, which they’re using for documentation.
You can see our current GOV.UK Pay documentation here. We’re always making improvements and we’d be interested in your feedback so please share your thoughts in the comment section below.
Sign up now for email updates from this blog or subscribe to the feed.
If this sounds like a good place to work, take a look at Working for GDS - we're usually in search of talented people to come and join the team.
7 comments
Comment by Beth posted on
The anchor links in the GOV.UK Pay docs don't seem to be working - eg https://gds-payments.gelato.io/reference/docs/quick-start-guide-to-the-api. Works in the left-hand nav, but not in the links in the body text.
Thanks for the useful post though - it's interesting to see the drawbacks of the different tools available.
Comment by Paulo Monteiro posted on
@Beth Thank you for noticing that.
I can confirm the issue and I will report it to the Gelato.io support team.
Comment by Nik Wakelin posted on
@beth: Sorry about the issue there! We're working on getting that fixed now 😀
Comment by Nik Wakelin posted on
Hiya Beth,
Just to let you know we've now fixed this one up!
Cheers,
Nik
Comment by Adam Londero posted on
If you host GOV.UK Pay on AWS or Azure you could try out their API Gateway or API Management respectively. Both allow you to provide Swagger definitions to automatically generate a developer portal to allow users to play with your APIs. May be more expensive than Gelato though?
Comment by Perle posted on
Aws API gateway is a pure gateway like Kong for example. And doesnt offer any true Dev Portal capabilities nor API analytics at the moment.
Comment by Paulo Monteiro posted on
Thank you for the suggestion.
I had a look at AWS http://swagger.io/getting-started-with-the-amazon-swagger-importer/ and it seems something that is worth having a look in the future.
It seems that the main limitation is the lack of an overview section and ability to add personalised documentation, which is something that is at the moment required.
Azure was not considered.