Documenting the API is easy with Swagger.

Tram Ho

APIs (Application Programming Interfaces) are becoming more and more popular, most services on the Internet use standard RESTfull APIs to give partners a portion of their resources to use. So the question is, how do we let partners know what resources they are provided with? What information must be used to get that resource?

Therefore, we need to have a tool to support the creation of document APIs that facilitates provision of resource usage through APIs effectively. Today we will learn about a fairly famous tool for writing document APIs: Swagger.

What is Swagger?

Swagger is an open source for developing, designing, building and documenting RESTfull Web Service systems.

Swagger provides tools for creating docs: Swagger UI, Swagger Editor, Swagger Codegen, Swagger Hub, Swagger Inspector. In which the first 3 tools are open source, Swagger Hub and swagger Inspector are more advanced tools but will have to pay fees, but we can use it for free for 30 days. So for the sake of convenience, we will learn the doc APIs with SwaggerUI and a brief overview of Swagger Hub. Swagger UI is a tool that helps gen a html css page describing APIs configured by a .yaml file. In addition, this tool also allows us to mockup to the api to see the results (of course, your api must work already.

Install Swagger UI

Step 1 : Download Swagger UI library

In essence, to display a document API for the user to read, only two things are needed, namely the Swagger UI library and the document API file written in the Swagger syntax and structure with the format * .yaml . To install it in your project, do the following:

Perform pull swagger-ui library from its github page into your project as follows:

Then copy the dist folder in that project into your project and choose render file index.html in the dist folder.

As in my project using Ruby on Rails as backend, I will copy it to public / swagger directory and add routes.rb root to: redirect("/swagger/index.html")

Then configure in the config / routes.rb file so that Rails can get the path to the static html file to run the document API screen:

Then, if we run localhost: 3000 on the browser, we will get the Swagger UI demo page below.

Step 2 : Create a config configuring your APIs

The basic structure of a .yaml file in Swagger is as follows:

openapi : The version of Swagger in use, will define the entire .yaml file structure

info : Information of APIs, which will contain sections: title, version, description, …

title : Open-APIs name (usually the product name of the project I work on)

vertion : Public APIs version

description : Description of APIs

security : Authentication that APIs use to provide resources

paths : The APIs you provide to the partner

component : Defines the models used by the APIs

There are also many other keywords that can be referenced in Swagger’s document page.

Swagger also supports writing config in json format, however we should write in yaml format.

We will create a .yaml file with the following structure to configure the APIs:

Thus, with only about 30 minutes along the document, we have a fairly complete config file about APIs information. As per the above configuration, we can configure the data resources to be sent to APIs and the APIs data returned as models (configured in components / schemas) for reuse.

Then, we save the configuration file as .yaml extension to the dist folder in step 1, here I will save it as swagger.yaml .

The directory structure is as follows:

Step 3 : Update the path of the config APIs file and enjoy the results

Now open the index.html file in the dist folder, find and edit the SwaggerUIBundle function url’s path to the path we just created.

Once installed, start the Rails server and go to the path: http: // localhost: 3000 / swagger / dist / index.html , I will have the following results:

The displayed results should be very understandable and intuitive. However, the problem with this solution is that the Swagger UI library has a capacity of almost 200MB, and it is pushed directly into the sourecode of my project, which is really bad, and the Getting to the URL document API directly on the running API server also makes it easy to reveal the structure of the API, because in fact the interface of the Swagger UI is a static file and it only handles the returned response. Think of it like Postman, but it provides a description for the API only.


Above, we have learned about a tool to write and manage document APIs that is easy to get acquainted with and self-written (easier than code html). Hope this article will help your project. Thanks for reading to the end of the article!

Share the news now

Source : Viblo