[API] Swagger – Tool to help describe the API structure

Tram Ho

Certainly when working with APIs, building documents (API specifications), functions, parameters, respones is essential. If you are having difficulty setting this description or don’t want to specify it on non-standard excel files, consider using Swagger.

Swagger allows you to specify the structure of your APIs so that machines can read them. The ability to describe the API as far as “root” is a great thing that Swagger brings.

Not only does Swagger specify APIs structure, it can do much more with a diverse ecosystem such as creating a stub server for APIs, creating a library of clients in 40 languages ​​or being able to test API on Swagger itself. However, within the scope of this article, I only talk about the file structure that Swagger uses to specify the API.


1. Basic Structure

Swagger can be written as JSON or YAML . In this tutorial, we only use the YAML example, but JSON works equally well. A Swagger with YAML format will look like this

So let’s take a look at what its components are 😄

2. Metadata

Starting for each Swagger starting with version , 2.0 is currently its final version. Version helps translators understand the overall structure of the next content.

Next, you need to define information about the API in the info with the title , description (optional), version (API version, not the version of the file or Swagger)

3. Base URL

Base URL is the section used for all API definitions including: schemes , host , basePath :

All API links are related to this base URL. For example /users actual /users means https://api.example.com/v1/users .

4. Consumes, Produces

The Consumes and produces defines the MIME type supported by the API. The “Root-level” definition can be overridden by separate operators (specific APIs can redefine this section).

5. Path

This section is important, defining each specific API and HTTP method supported in these APIs. GET /users are described as follows:

6. Parameters

Operators may need parameters based on URL path ( /users/{userId }), query string ( /users?role=admin ), headers (X-CustomHeader: Value) and in the request body. You can define parameter types, structures, detailed descriptions, requirements or options or other information in the swagger as follows:

7. Responses

Each API of course responds to a status (status codes) such as 200 OK or 404 Not Found and schema (structure) of the response body. These schemas can either be defined directly in the respone or can be separated from the definition outside the $ref cell

8. Input and Output Models

The definitions section defines common data structures to use in your API. This part can be referenced via $ref any shema – both in the request body and the response body. For example this is JSON object:

Can be described by

And referenced in the request and response schemas body schema body following through $ref :

9. Authentication

The keywords securityDefinitions and security are used to describe methods that require authentication.

Supported verification methods include:

  • Basic authentication
  • API key (as a header or query parameter)
  • OAuth 2 common flows (implicit, password, application and access code)


Share the news now

Source : Viblo