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, most importantly, is automatically updated whenever we update our API specification.
We already had our API defined in OpenAPI/Swagger 2.0, but it was a static definition and never used to generate the API documentation, not to mention automatic code generation.
Let’s clarify Swagger vs OpenAPI
In the last years, there have been many questions and confusion about the difference between Swagger and OpenAPI, when to use one over the other, and the relationship between OpenAPI and Swagger.
The OpenAPI is the official name of the specification, and the OpenAPI Initiative manages the development of the specification. Swagger is associated with some of the most well-known and widely used tools for implementing the OpenAPI specification. The Swagger toolset includes a mix of open-source, free, and commercial tools, which can be used at different stages of the API lifecycle. You can read more about their tools from their official blog.
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 the OpenAPI Initiative page that manages the specification. 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.X Specification.
The main benefits of definition driven API development, in my personal opinion, are:
- better developer experience
- faster go to market
- increased team independence.
- Automated documentation and code generation
You can read more about the benefits of definition driven API development here, and I also suggest reading this post about API driven development.
Validating your API specifications
Many organisations maintain their API style guides. These documents detail the decisions already made regarding 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 validate our Open API specification automatically, 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.
OpenAPI specification in action
We have taken advantage of the benefits provided by OpenAPI specification and described our APIs to generate good looking API documentation pages with code examples automatically. In Part 2, we will discuss using Open API specification and some fantastic tools to create code examples and SDKs automatically.
You are more than welcome to take a look at our API documentation if you are interested in how does automatically generated documentation look — our API documentation.
In addition to that, if you are considering setting up automatically generated API documentation and still have some questions to figure out, don’t hesitate to reach out for advice. We are happy to share our experience in more detail and help in any way we can.
Tanel Tähepõld (founder of PDF Generator API)