Swagger – Document tool for RESTfull APIs

Tram Ho


For a large project, writing an API, creating a Document for the project is not a simple task. In the case of continuous requirement updates from customers, it becomes more and more time consuming.

But without constant updates, it will be very difficult for other developers to use our API, as well as difficult to test the API.

Currently there are many open source tools to help programmers can write clear documents and can test the endpoint directly without using tools like postman to test API. Current variables are Swagger and API Blue Print.

In this article, I would like to introduce a tool that is SWAGGER, it helps us to write restfull standard documents easily for our project. And please note that it supports many languages, not just Ruby.


I will write API with Ruby on Rails language

1. Build the API

You can refer to the document: http://apionrails.icalialabs.com/book/ to create your own Project. Or you can quickly create a rails project to test as follows:

Then add the following 2 gems to Gemfile:

then run bundle install .

2. Document for API

2.1 What is Swagger?

  • Is an open source toolkit for building OpenAPI specifications that enables us to design, build documentation, and use REST APIs.
  • Swagger provides 3 main tools for developers:

    Swagger-Editor is used to design new APIs or edit existing APIs via a config file.

    Swagger-Codegen is used to generate code from existing config files.

    Swagger-UI is used to generate html, css, etc. files from a config file.

  • Writing documents for Swagger has two main approaches:

    Top-down approach : designing APIs before coding.

    Bottom-up approach : from the existing API design config files to describe them

  • To make it easier to understand, you can access the demo link with Swagger UI http://petstore.swagger.io/ .
  • With each API we can know the input and output details as well as which fields are required to submit, and what status the results can receive. In particular, we can input data to test the results.

2.2 Install Swagger UI

  • Config wagger block:

    Each doc will go together in the form of 1 action – 1 controller Swagger Block provides a method: Swagger :: Blocks.build_root_json is responsible for accepting classes that have no API information.

    If following the instructions of gem swagger-block , we can configure the controller, but the problem is that the controller will be very big if placed doc there.

    In addition, if you already know about the MVC pattern, or the SOLID principle, configuring the Controller is not recommended. Therefore, I will create a swagger folder to store the files related to swagger requests

    Then include it into the controller :

  • Response and Parameters:

    Response and parameters are very common in APIs. For example, after API login, you will have to return the User information. In the API show / edit user information, you will also have to return the User information, etc. We will have to find a way to reuse the code.

    • Response :

      In SwaggerUI, we can use $ ref to call a schema that has already been defined. Imagine it as a link to point to another JSON Schema.

      Then you need to include it in model user.rb

      In addition, normally we will have 1schema ErrorSchema – it will be used when the API returns error information.

      Next, we need to create the common_response file to use the above schema

    • Parameters :

      Just like the Response part, the Parameter will also be shared by many APIs, so we will also conduct a separate definition of these parameters. For example token authentication or fields id

      Next, we declare it into the root file of swagger

      Finally, the installation is complete, all that’s left now is to use swagger into the API

      Now, let’s look back at our project structure:

2.3 Setup Swagger UI

The result above, we have 1 json file full information already. The task now is just how to show it to the client for easy viewing. We will use gem “swagger_ui_engine”

Perform the gem add on the gem file, run bundle and finally the configuration step of it in the config / routes.rb file

Now, we start the server and access the link: / api_docs, you will see your result.

Share the news now

Source : Viblo