How we use Open API v3 specification to auto-generate API documentation, code-snippets and clients
Poor or non-existent documentation is one of the five reasons why developers never use your API. So we wanted to make sure that our API documentation is clear, complies with standards and what is most important — is automatically updated whenever we update our API specification.
We already had our API defined in Swagger 2.0, but it was a static definition and never used to generate the API documentation, not to mention automatic code generation.
The benefits of OpenAPI specification
I expect that most of you are familiar with OpenAPI, but to whom it is new, here is a quick introduction from Swagger About page who started the movement. The OpenAPI specification is an API description format for RESTful APIs. The specification allows defining the entire API structure from available endpoints to parameters and authentication methods. The API specification can be written in YAML or JSON. The complete OpenAPI Specification can be found on GitHub: OpenAPI 3.0 Specification.
The main benefits of definition driven API development are better developer experience, faster go to market and increased team independence. You can read more about the benefits of definition driven API development here and I also suggest reading the post about API driven development.
Validating your API specifications
Many organisations maintain their API style guides. These documents detail the decisions already made in terms of resource naming, capitalisation, versioning, and other elements on how the API needs to look and feel.
Although if these style guides are not enforced, we will end up with inconsistent API specifications. While manual reviews are essential, you can also turn to automation to help implement your style guide.
While searching for a way to automatically validate our Open API specification we found Spectral (created by Stoplight) an awesome JSON/YAML linter for creating automated style guides. Spectral allows you to describe your API style guide as a set of rules, so you can automatically validate your Open API specification against your API guidelines and make sure that everyone is following them.
Generating API documentation
There are a lot of different tools and services which allow you to display live API documentation from the OpenAPI specification. You can either self-host the API documentation using tools like ReDoc or Swagger UI or go with a SaaS which provides hosted documentation. Usually, these services offer not only the API documentation capabilities but cover the full API lifecycle. In that category, we have Postman, Stoplight, Swagger Hub, ApiMatic, to name a few.
After trying out different services, we finally chose to self-host the ReDoc as we liked their three-column design and how they present the endpoint parameters, with example payloads and responses.
We also loved how easy it was to deploy the documentation with ReDoc. You can just use their bundled JavaScript and specify URL to your Open API specifications. The code snippet below is everything you need.
Generating code-snippets
Developers must be able to try your API as easily as possible. Therefore you should provide code samples in different programming languages. Creating and maintaining code samples in different languages can be complicated if you don’t have the know-how in the team.
After doing some research on the Internet, we found this small node module which uses the openapi-snippet generator to create code samples and enrich your Open API specification. You can just run the following command, and you will have code samples for each of your API endpoints.
./node_modules/.bin/snippet-enricher-cli --input=openapi.yaml > openapi-with-examples.jsonAnd the result is nice looking code samples in your documentation.
Generating HTTP API clients
If managing code-snippets is time-consuming, then keeping your API clients up to date is a nightmare, especially if you have a small team. So, besides generating code-snippets for each API endpoint, we also wanted to auto-generate HTTP clients for our API.
This task turned out to be more complicated than we initially thought, but we ended up with the OpenAPI Generator, which is a fork from Swagger Code Generator. The main advantages of the OpenAPI Generator were better documentation and the easy to use node module. What we found important was specifying a configuration file for each programming language. You can find a set of available configuration options for each language here.
We also created a small bash script to help us automate the code generation and fix some issues in the generated README file. We have another script that automatically pushes client updates to GitHub. This means that by running a single bash script, we create HTTP clients for five target languages (Python, Java, JavaScript, PHP and Ruby) and publish updates to GitHub.
If you wish to know more about Open API Generator then I suggest reading the Introduction to OpenAPI Generator by Kristopher Sandoval on Nordic APIs.
Summary
The chosen tools were only the best for us, and I suggest that before you start documenting your APIs, you would also do your research with some trials on different tools. You might find some other combination that suits you much better. Selecting the right tooling will save you a lot of time. The good part is that once you have the specification is done, it’s easy to try out different tools and hosting options as well.
Also, this short piece didn’t cover an essential part of the API development process — the testing. Many of the tools named above — like Postman and Swagger provide means to automate your API testing and make it part of your API development process. Hopefully, this is something I will cover in the next blog post.
