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.
Demo:
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
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 | <span class="token key atrule">swagger</span> <span class="token punctuation">:</span> <span class="token string">"2.0"</span> <span class="token key atrule">info</span> <span class="token punctuation">:</span> <span class="token key atrule">title</span> <span class="token punctuation">:</span> Sample API <span class="token key atrule">description</span> <span class="token punctuation">:</span> API description in Markdown. <span class="token key atrule">version</span> <span class="token punctuation">:</span> 1.0.0 <span class="token key atrule">host</span> <span class="token punctuation">:</span> api.example.com <span class="token key atrule">basePath</span> <span class="token punctuation">:</span> /v1 <span class="token key atrule">schemes</span> <span class="token punctuation">:</span> <span class="token punctuation">-</span> https <span class="token key atrule">paths</span> <span class="token punctuation">:</span> <span class="token key atrule">/users</span> <span class="token punctuation">:</span> <span class="token key atrule">get</span> <span class="token punctuation">:</span> <span class="token key atrule">summary</span> <span class="token punctuation">:</span> Returns a list of users. <span class="token key atrule">description</span> <span class="token punctuation">:</span> Optional extended description in Markdown. <span class="token key atrule">produces</span> <span class="token punctuation">:</span> <span class="token punctuation">-</span> application/json <span class="token key atrule">responses</span> <span class="token punctuation">:</span> <span class="token key atrule">200</span> <span class="token punctuation">:</span> <span class="token key atrule">description</span> <span class="token punctuation">:</span> OK |
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.
1 2 | <span class="token key atrule">swagger</span> <span class="token punctuation">:</span> <span class="token string">"2.0"</span> |
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)
1 2 3 4 5 | <span class="token key atrule">info</span> <span class="token punctuation">:</span> <span class="token key atrule">title</span> <span class="token punctuation">:</span> Sample API <span class="token key atrule">description</span> <span class="token punctuation">:</span> API description in Markdown. <span class="token key atrule">version</span> <span class="token punctuation">:</span> 1.0.0 |
3. Base URL
Base URL is the section used for all API definitions including: schemes
, host
, basePath
:
1 2 3 4 5 | <span class="token key atrule">host</span> <span class="token punctuation">:</span> api.example.com <span class="token key atrule">basePath</span> <span class="token punctuation">:</span> /v1 <span class="token key atrule">schemes</span> <span class="token punctuation">:</span> <span class="token punctuation">-</span> https |
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).
1 2 3 4 5 6 7 | <span class="token key atrule">consumes</span> <span class="token punctuation">:</span> <span class="token punctuation">-</span> application/json <span class="token punctuation">-</span> application/xml <span class="token key atrule">produces</span> <span class="token punctuation">:</span> <span class="token punctuation">-</span> application/json <span class="token punctuation">-</span> application/xml |
5. Path
This section is important, defining each specific API and HTTP method supported in these APIs. GET
/users
are described as follows:
1 2 3 4 5 6 7 8 9 10 11 | <span class="token key atrule">paths</span> <span class="token punctuation">:</span> <span class="token key atrule">/users</span> <span class="token punctuation">:</span> <span class="token key atrule">get</span> <span class="token punctuation">:</span> <span class="token key atrule">summary</span> <span class="token punctuation">:</span> Returns a list of users. <span class="token key atrule">description</span> <span class="token punctuation">:</span> Optional extended description in Markdown. <span class="token key atrule">produces</span> <span class="token punctuation">:</span> <span class="token punctuation">-</span> application/json <span class="token key atrule">responses</span> <span class="token punctuation">:</span> <span class="token key atrule">200</span> <span class="token punctuation">:</span> <span class="token key atrule">description</span> <span class="token punctuation">:</span> OK |
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:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 | <span class="token key atrule">paths</span> <span class="token punctuation">:</span> /users/ <span class="token punctuation">{</span> userId <span class="token punctuation">}</span> <span class="token punctuation">:</span> <span class="token key atrule">get</span> <span class="token punctuation">:</span> <span class="token key atrule">summary</span> <span class="token punctuation">:</span> Returns a user by ID. <span class="token key atrule">parameters</span> <span class="token punctuation">:</span> <span class="token punctuation">-</span> <span class="token key atrule">in</span> <span class="token punctuation">:</span> path <span class="token key atrule">name</span> <span class="token punctuation">:</span> userId <span class="token key atrule">required</span> <span class="token punctuation">:</span> <span class="token boolean important">true</span> <span class="token key atrule">type</span> <span class="token punctuation">:</span> integer <span class="token key atrule">minimum</span> <span class="token punctuation">:</span> <span class="token number">1</span> <span class="token key atrule">description</span> <span class="token punctuation">:</span> Parameter description in Markdown. <span class="token key atrule">responses</span> <span class="token punctuation">:</span> <span class="token key atrule">200</span> <span class="token punctuation">:</span> <span class="token key atrule">description</span> <span class="token punctuation">:</span> OK |
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
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 | <span class="token key atrule">paths</span> <span class="token punctuation">:</span> /users/ <span class="token punctuation">{</span> userId <span class="token punctuation">}</span> <span class="token punctuation">:</span> <span class="token key atrule">get</span> <span class="token punctuation">:</span> <span class="token key atrule">summary</span> <span class="token punctuation">:</span> Returns a user by ID. <span class="token key atrule">parameters</span> <span class="token punctuation">:</span> <span class="token punctuation">-</span> <span class="token key atrule">in</span> <span class="token punctuation">:</span> path <span class="token key atrule">name</span> <span class="token punctuation">:</span> userId <span class="token key atrule">required</span> <span class="token punctuation">:</span> <span class="token boolean important">true</span> <span class="token key atrule">type</span> <span class="token punctuation">:</span> integer <span class="token key atrule">minimum</span> <span class="token punctuation">:</span> <span class="token number">1</span> <span class="token key atrule">description</span> <span class="token punctuation">:</span> The ID of the user to return. <span class="token key atrule">responses</span> <span class="token punctuation">:</span> <span class="token key atrule">200</span> <span class="token punctuation">:</span> <span class="token key atrule">description</span> <span class="token punctuation">:</span> A User object. <span class="token key atrule">schema</span> <span class="token punctuation">:</span> <span class="token key atrule">type</span> <span class="token punctuation">:</span> object <span class="token key atrule">properties</span> <span class="token punctuation">:</span> <span class="token key atrule">id</span> <span class="token punctuation">:</span> <span class="token key atrule">type</span> <span class="token punctuation">:</span> integer <span class="token key atrule">example</span> <span class="token punctuation">:</span> <span class="token number">4</span> <span class="token key atrule">name</span> <span class="token punctuation">:</span> <span class="token key atrule">type</span> <span class="token punctuation">:</span> string <span class="token key atrule">example</span> <span class="token punctuation">:</span> Arthur Dent <span class="token key atrule">400</span> <span class="token punctuation">:</span> <span class="token key atrule">description</span> <span class="token punctuation">:</span> The specified user ID is invalid (e.g. not a number). <span class="token key atrule">404</span> <span class="token punctuation">:</span> <span class="token key atrule">description</span> <span class="token punctuation">:</span> A user with the specified ID was not found. <span class="token key atrule">default</span> <span class="token punctuation">:</span> <span class="token key atrule">description</span> <span class="token punctuation">:</span> Unexpected error |
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:
1 2 3 4 5 | <span class="token punctuation">{</span> <span class="token property">"id"</span> <span class="token operator">:</span> <span class="token number">4</span> <span class="token punctuation">,</span> <span class="token property">"name"</span> <span class="token operator">:</span> <span class="token string">"Minh NV"</span> <span class="token punctuation">}</span> |
Can be described by
1 2 3 4 5 6 7 8 9 10 11 12 | <span class="token key atrule">definitions</span> <span class="token punctuation">:</span> <span class="token key atrule">User</span> <span class="token punctuation">:</span> <span class="token key atrule">properties</span> <span class="token punctuation">:</span> <span class="token key atrule">id</span> <span class="token punctuation">:</span> <span class="token key atrule">type</span> <span class="token punctuation">:</span> integer <span class="token key atrule">name</span> <span class="token punctuation">:</span> <span class="token key atrule">type</span> <span class="token punctuation">:</span> string <span class="token comment"># Both properties are required</span> <span class="token key atrule">required</span> <span class="token punctuation">:</span> <span class="token punctuation">-</span> id <span class="token punctuation">-</span> name |
And referenced in the request and response schemas body schema body following through $ref
:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 | <span class="token key atrule">paths</span> <span class="token punctuation">:</span> /users/ <span class="token punctuation">{</span> userId <span class="token punctuation">}</span> <span class="token punctuation">:</span> <span class="token key atrule">get</span> <span class="token punctuation">:</span> <span class="token key atrule">summary</span> <span class="token punctuation">:</span> Returns a user by ID. <span class="token key atrule">parameters</span> <span class="token punctuation">:</span> <span class="token punctuation">-</span> <span class="token key atrule">in</span> <span class="token punctuation">:</span> path <span class="token key atrule">name</span> <span class="token punctuation">:</span> userId <span class="token key atrule">required</span> <span class="token punctuation">:</span> <span class="token boolean important">true</span> <span class="token key atrule">type</span> <span class="token punctuation">:</span> integer <span class="token key atrule">responses</span> <span class="token punctuation">:</span> <span class="token key atrule">200</span> <span class="token punctuation">:</span> <span class="token key atrule">description</span> <span class="token punctuation">:</span> OK <span class="token key atrule">schema</span> <span class="token punctuation">:</span> <span class="token key atrule">$ref</span> <span class="token punctuation">:</span> <span class="token string">'#/definitions/User'</span> <span class="token key atrule">/users</span> <span class="token punctuation">:</span> <span class="token key atrule">post</span> <span class="token punctuation">:</span> <span class="token key atrule">summary</span> <span class="token punctuation">:</span> Creates a new user. <span class="token key atrule">parameters</span> <span class="token punctuation">:</span> <span class="token punctuation">-</span> <span class="token key atrule">in</span> <span class="token punctuation">:</span> body <span class="token key atrule">name</span> <span class="token punctuation">:</span> user <span class="token key atrule">schema</span> <span class="token punctuation">:</span> <span class="token key atrule">$ref</span> <span class="token punctuation">:</span> <span class="token string">'#/definitions/User'</span> <span class="token key atrule">responses</span> <span class="token punctuation">:</span> <span class="token key atrule">200</span> <span class="token punctuation">:</span> <span class="token key atrule">description</span> <span class="token punctuation">:</span> OK |
9. Authentication
The keywords securityDefinitions
and security
are used to describe methods that require authentication.
1 2 3 4 5 6 | <span class="token key atrule">securityDefinitions</span> <span class="token punctuation">:</span> <span class="token key atrule">BasicAuth</span> <span class="token punctuation">:</span> <span class="token key atrule">type</span> <span class="token punctuation">:</span> basic <span class="token key atrule">security</span> <span class="token punctuation">:</span> <span class="token punctuation">-</span> <span class="token key atrule">BasicAuth</span> <span class="token punctuation">:</span> <span class="token punctuation">[</span> <span class="token punctuation">]</span> |
Supported verification methods include:
- Basic authentication
- API key (as a header or query parameter)
- OAuth 2 common flows (implicit, password, application and access code)