How to use Swagger (Open API) to document your Rails API
Swagger, also known as Open API, allows your application to create documentation as you develop your API. Documentation is always appreciated and provides a lot of value to a development team (devs and QA) by saving time that other ways would be spent by investigating and mapping how a specific API endpoint behaves. In this article, we are going to get a glimpse of what swagger is, how to implement it, and how it is going to be used for any future development and expansion of your API.
Swagger 2.0 allows you to describe the structure of your APIs so that machines can read them. By reading your API’s design, swagger builds interactive API documentation. It can also automatically generate client libraries for your API in many languages and explore other possibilities like automated testing. Swagger does this by asking your API to return a YAML or JSON that contains a detailed description of your entire API. This file is essentially a resource listing of your API which adheres to OpenAPI Specifications. The specification asks you to include information like:
- What are all the operations that your API supports?
- What are your API’s parameters and what does it return?
- Does your API need some authorization?
Swagger is now known as Open API, and as of the writing of this article, the most recent version of the standard is Open API 3, which is compatible with Swagger 2.0. Open API 3 changes the tooling structure it uses to create the documentation, but the workflow is pretty much unchanged. All the procedures in this article are going to be for Swagger 2.0.
The main premise of Swagger is to let the code document itself, this is achieved by letting you write a Swagger spec for your API manually, or have it generated automatically from annotations in your source code. It depends on how far are you in the development of your API, if you are in the early stages of development you can integrate Swagger from the start, but if your development is further along you may want to use the manual route.
In case you don’t want to use any specs or gems to generate the swagger file automatically or you are just too far into your project but not far enough to spend the time creating it, there is a way to make the swagger file manually. First, you have to create a swagger folder and inside it create a swagger.yml. That file has a very specific structure that you can check out in the OpenApi specification to check how to write parameters and responses from the endpoints. The basic jist of the file is: You define paths for the endpoints in your API, and for those paths you define request methods, inside each method, you define the summary and the description of what you expect it to do and the schema for the body of the request and for the response from the server. Additionally, you can add different response codes and different response schemas for each code. One thing that is not very easy to find in the documentation is how you group different endpoints related to each other, this is achieved by using tags on the path. A tag will create a collapsible group that will have all the endpoints that share the same tag, creating a neat way to visualize your documentation. Finally, to access your API’s documentation page, go to the Swagger UI URL.
For those of you that don’t want to go through the hustle of creating the swagger file by hand, there are several gems that help you generate documentation from tests using RSPEC, they all have pretty similar behavior but for our case, we are going to use rswag as the example.
The first thing you have to do is install the gem into your project by adding it to the Gemfile and running bundle install. Then you need to create the generators for rswag with the command rails generate rswag:install. And finally create the specs that are going to be used to map the endpoints by using the command rails generate rspec:swagger API::MyController. After that, you are ready to go and keep creating specs to describe your endpoints and rswag will generate the swagger file automatically by running rake rswag:specs:swaggerize. It can get more complex than this but I just showed you the simple way of documenting your API, if you want to learn more you can go to the rswag documentation and go as deep as you feel.
We just learned two ways to document your API while coding. It is worth noting that you should start any project with the mindset of using self-documenting gems to create the documentation for your project because once you start is very difficult to implement down the line unless you use other types of technologies that generate the swagger file for you and you pick it up from there (there are tools used by DevOps people that can help with this). With this said the only thing left is for me to thank you for reading all the way through this article, I hope you found it useful and if you liked it give it a clap, check out my other articles on different topics, and consider following me to get notified every time I get new articles out.
