Learn about Swagger – Document writing tool for RESTfull APIs

Tram Ho

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

Therefore, we need to have a tool to support the creation of document APIs to facilitate the provision of efficient use of resources through APIs. Today we will learn about a famous tool to write document APIs: Swagger.

What is Swagger?

Swagger is an open source used to develop, design, build, and document RESTFull Web Service systems. We have Swagger demo as follows:

Swagger provides doc creation tools: Swagger UI, Swagger Editor, Swagger Codegen, Swagger Hub, Swagger Inspector. The first 3 tools are open source, Swagger Hub and swagger Inspector are more advanced tools but will have to pay, but we can use it for free for 30 days. So for convenience, we will learn to write doc APIs using SwaggerUI.

Swagger UI is a tool that helps create a html css page describing APIs configured by a .yaml file. In addition, this tool also allows us to mockup to that API to see the results.

In Ruby on Rails, there are gem swagger-docs and swagger-ui that support writing ruby ​​code to render yaml files, but there are still some errors such as examples that cannot be displayed or errors about using oneOf. fix and these gems require rspec so will only work well on the local environment. Therefore we will learn to write directly with yaml syntax instead of using gem.

Install Swagger UI

1. Download the swagger library

You clone this Github project , then copy the dist folder in that project into your project and select render file index.html in the dist directory. As in my project using Ruby on Rails as a backend, I will copy it to the public/swagger folder and add the routes.rb file root to: redirect("/swagger/index.html")

This way the app’s root path will point to swagger’s index.html file.

2. Directory structure

To facilitate the management of the API, we will split yaml file into files and divide into folders. The basic structure of the directory is as follows:

index.yaml is the main configuration file for API docs, containing paths

paths contain the main define files of APIs, we will divide by controller for easy management

The definitions contain object descriptions for the API, which we will divide by models

shared contains common declarations like common errors, pagination infor

3. Syntax $ ref

The nice thing about the .yaml file is that we can separate each section and recall them using $ ref. Because of this, we can separate the data structures into separate parts like the above directory structure and then call them back. This makes our .yaml file have an easy-to-read and understandable structure. To know specifically, you need to read the document of swagger.

The syntax for using $ ref can be summarized as follows:

  • Point to the lement of the document on the same file – $ref: 'document.json#/myElement'
  • Point to the element’s document located in the parent directory – $ref: '../document.json#/myElement'
  • Point to the element’s document located in any directory – $ref: '../another-folder/document.json#/myElement'

2. Create a configuration of 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, this section will contain sections: title, version, description, …

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

vertion : APIs public version

description : Description of APIs

security : Authentication that APIs use to provide resources

paths : APIs that you provide to partners

definitions : Defines the models used by APIs

There are also many other keywords can refer to the document page of Swagger.

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

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

Here we will have divided paths by controller, the Restful structure in rails has 7 actions but normally when writing API, there are only 5 commonly used actions: index, create, show, update, delete. In particular, index and create do not require ID, while the remaining actions require ID, with the purpose that each .yaml file in paths will declare a resource by controller so we need to add the key index_create and show_update (the key can be set arbitrary) to distinguish.

File paths / users.yaml

File definitions / user.yaml

File definitions / commons.yaml

Edit the index.html file in the swagger folder

After all, start the server to see what your results are.

Summary

So we have learned and written a basic API documents using yaml syntax with swagger. In addition, we can also divide yaml files into directories that suit the API writing structure with Ruby on Rails for easy management. Swagger also has many interesting keywords for us to learn and apply to our project. And now we can write API docs that no longer depend on Ruby gem.

Share the news now

Source : Viblo