2 approaches to documenting REST API
The article is intended for individuals who are already familiar with the OpenAPI specification. If you do not know anything about the REST API and how to document it, head over to an excellent source of knowledge for documenting a REST API written by Tom Johnson.
Introduction
While working on a back-end system, you need to think of how you will expose the functionalities you’re creating. There are many strategies for data exchange such as SOAP, REST, GraphQL, and gRPC. However, we will concentrate on REST, specifically on how to document a REST API. Documentation in this context is indispensable to the product you’re developing since exposing the endpoints may be the only way to connect to your product.
The article is intended for individuals who are already familiar with the OpenAPI specification. If you do not know anything about the REST API and how to document it, head over to an excellent source of knowledge for documenting a REST API written by Tom Johnson.
Naming confusion
Many people use the tems Swagger and OpenAPI interchangeably to refer to a specification that looks like this. However, the difference is fundamental and the term confusion originates from past events.
OpenAPI is a specification that was adopted in the industry while Swagger refers to a set of Smartbear tools used for implementing the specification, i. e. Swagger UI and Swagger Editor among many other tools. Smartbear, who owned the specification, launched the OpenAPI Initiative funded by the Linux Foundation. The founding members such as Microsoft, Google, IBM, and more adopted the specification and rebranded it as OpenAPI Specification. Nevertheless, Swagger is still erroneously referenced to the OpenAPI spec as the specification itself.
Monolithic and unmaintainable OpenAPI spec
The problem with what you will find in most tutorials and demo presentations is the approach of documenting the endpoints in one single file. Take a look at the official example of Swagger Petstore — OpenAPI 3.0 (also see the rendered spec).
It contains 819 lines of code. Manageable to maintain but cumbersome. However, the problem is that real-life projects are much more complicated than a pet store example. I’ve seen projects that had thousands of code lines in one specification. So, how can we go about maintaining it? There are two main approaches to tackling this problem, automated and manual. The automated approach would generate the OpenAPI spec from the source code with parsers while the manual approach would require a person to create a structure for the specification that would be later bundled into one OpenAPI specification. I will briefly cover these approaches in the sections below. If the topic piqued your interest, I recommend delving into the links in this post.
Approach 1: Automated process
You can find many tools that extract OpenAPI Specification from the comments and annotations in the source code. These tools can generate REST API documentation from the extracted specification in a browser that uses a human-friendly user interface. On top of that, you can also generate clients (also known as SDKs) for your API, for most popular programming languages.
Some popular tools:
Approach 2: Manual process
The manual process lets you think about how your API contract may look before you start coding it. It can be an exercise that will help you think about the consistency of your API contract.
An example structure of the REST API documentation may look like this:
rest/ - The folder that contains all the API specification
openapi.yaml- The file from where the API specification is built.
This file should contain general information about the API and server, and the definition of the endpoint URLs. Each of the endpoint URLs should point to a file in the endpoints folder. In addition, this file should also contain the tags, which define the grouping structure of the endpoints. For example, the project-related endpoints can be tagged with Project tag. which would define the grouping structure of the endpoints.
endpoints/- This folder should contain the definitions of the endpoints.
The sub-folders should be divided by tag. Endpoint definitions should make use of the files in parameters, examples and schemas.
parameters/- This folder should contain the definition of path and query parameters used by the endpoints.
The sub-folders should be divided into path and query parameters, or more if needed. Parameters can be used across different tags. Path parameters are mandatory parameters that make up the URL of the endpoint. Query parameters are used as optional parameters that modify the behavior or output of the endpoint.
examples/- This folder should contain example request and response bodies.
The sub-folders should be divided by tag, and further split into request and response examples. The examples should be in .json format to facilitate easier documentation.
schemas/- This folder can be located in therestdocumentation folder or closer to the code where endpoints are defined.
Schemas should contain the definition of the REST contract, and contain the rules that request and response bodies must follow. The sub-folders should be divided by tag, and further subdivided by request/response. Schemas can be factored out to be used over different endpoints, You should be careful with factoring out schemas since the fields that are required can be different for different endpoints.
How do I put together all these files?
To start leveraging reusable elements and simplify the specification by distributing it, a $ref keyword will be essential to achieve that goal. With $ref, you can reference elements that will be bundled into one OpenAPI definition. The $ref keyword gives us enough leeway to create a tailored structure for yourREST API reference. If you want to learn more about $ref, head over to an official guide.
Example for a distributed OpenAPI spec
I strongly recommend starting with David Garcia’s OpenAPI boilerplate. This is where I started when I had a go with this approach for the first time. David used a Pet Store example to showcase how to maintain the lengthy OpenAPI spec in a maneuverable and responsive manner.
To bundle your distributed files, remember to install swagger-cli and run the command:
swagger-cli bundle openapi.yaml -o /tmp/openapi.json — dereference
Once you bundle your OpenAPI files, you should choose an OpenAPI renderer that will transform the spec into the user-friendly documentation with the UI.
Some popular renderers:
Conclusion
This short introduction to what you can do with OpenAPI is a pretaste of a much larger scope of possibilities. Follow the links in this post to delve deeper into the topic.
