How to write Rails API document

Tram Ho

As you know, an API application will not have a user interface on the browser, instead will be JSON or XML data … displayed only. Therefore, when writing an API application requires the writer to write the accompanying Documents to support the developers who use them and especially QA, who will have more difficulty understanding the author. use of the API.

There are many ways to write Documents, the simplest would be to manually write into Excel or Word files for example. Specify what API this is for, how to access the URL, what is the Request submission data, What is the Response Data … Then send them to Developers / QA as required. let them read. This method is quite manual and takes a lot of efforts while the value brought to its users is not necessarily high, because they simply do not have a uniform Format and it is easy to lack information.


Today I will introduce you to a famous tool in writing API docs, which is Swagger (UI). Specifically, what is Swagger, you can search to find out, so in the scope of this article, I would like to not reintroduce, instead I will go deep into how to deploy Swagger in “Science” and “Developer” as possible.

Back a bit, the previous posts when guiding the implementation of Swagger UI often approach towards copying UI of Swagger and then “throwing” into your Project (clone to Repository Swagger or copy CSS file, Swagger’s CSS) otherwise, write an XML file (JSON) and re-render them to View.

And the way that “Science” and in the direction of “Developers” here I want to mention is:

  • Being able to reuse code, write Docs as well as write Code, what’s the same is re-usable
  • Easy to scale (Scale), for example, when adding a field to the Model or renaming a field for example, the Documents file is automatically updated as well.
  • Organize Trees (Directory Tree) clearly and scientifically


In Rails, there are 2 Gems commonly used to Implement Swagger: swagger-docs and swagger-blocks . The biggest difference between these two gems is that swagger-blocks are supported to v2.0 of the Swagger Specification and swagger-docs only stop at v1.2, and according to swagger-docs repos, they have no plans yet. update to v2.0. Therefore in this Demo I will deploy with gem swagger-blocks.

Note: Both of the aforementioned gems do not generate a Swagger UI / UX interface, but only a .json file that matches the Swagger UI format, so to have an interface like Swagger bring us, 1 more Gem is swaggeruiengine .

To begin, create a Rails API application by typing the following commands on Terminal:

Then add 2 Gem I introduced above to Gemfile and bundle them:

Note: when deploying in reality, I encountered a problem when calling API with Postman tool – the tool that supports Test API requests – Oki but when Deploy on the Server and the call API back and forth between Servers was returned 404, then 1 when searching, I found out that it is due to the lack of CORS config. To fix it, you just need to add Gem as follows:

and config for Rails as follows:

On the Repo of the Swagger-Blocks gem there is a detailed introduction on how to set up Swagger, but I see some points that aren’t really “dry” code, so I will customize Swagger’s Trees (structure) in the Project his little bit to take advantage of the common use (reusing code that í) as the type of Paramerter often called or called the common Response (404 or 500 error for example). It also helps us to easily expand the code as needed in the future.

The directory structure of Swagger then looks like this:

Compared to the Repo document of Swagger-Blocks, my organization has a few points that I personally think will be clearer and clearer.

  • According to Swagger instructions, each Documents will correspond to a Controller, this writing is quite understandable, but you can easily recognize that the Controller will be swelled “extremely” quickly if you put Docs in it. And Controller is not an ideal place to handle Docs. Therefore, let’s split into a separate module – switch processing Docs. Specifically here I will put in concern / swagger folder and then Include back into Controller.
  • There will be many shared parameters, for example, the userID is shared when getting user information as well as updating user information, for example. So I created a parameter.rb file to contain things that are shared, when needed, I will include it in the Docs file (here is user_api.rb)
  • Similarly, there will be a lot of shared errors, type of error 401 – not authorize or 404 – not found Records so I created an error_response.rb file to write together, when needed again to include the file containing Docs (in This is user_api.rb)
  • The Response Success 200 although each API will return a different information, but not without common ground. For example, the following APIs all return User information after a successful Request: API show, API to edit User information and API login. Therefore, we must find a way to reuse the Code. Fortunately, with Swagger we can use $ ref to call a previously defined schema (here: user_schema.rb in modes / concern / swagger)

Note, you need to create a Router for Documents to know the URL in the browser.

After creating the Router, we also create a controller corresponding to this router and define API Documents basic parameters such as:

  • Version Swagger uses -Tittle, Description of API
  • API default path
  • The generated data type of the API (usually Json or possibly XML) ….

In the index method of api_docs_controller, remember to call the method to render the API information you want to write Docs.

Here you can turn on the server and go to the URL: localhost: 3000 / api_docs.json to see the result.

We will use gem swagger_ui_engine and config a little to get Swagger UI interface for the json data we just created above as follows:

Accomplished. Now you can restart the server, revisit the localhost URL: 3000 / api_docs to see the results.


Personally, I think Swagger is a great tool to create Documents for API which is quite simple and beautiful. Hopefully this article will more or less make it easier for you to write API in general and API Documents in particular.

Share the news now

Source : Viblo