In our previous article, we introduced Swagger and discussed its importance in API documentation. Now that we have a basic understanding of Swagger, it’s time to dive deeper into building your own Swagger step by step.
In this article, we will cover how to document API paths, methods, parameters, and responses using Swagger.
1. Understanding API Endpoints
An API endpoint is a specific URL at which a particular resource can be accessed. In Swagger, endpoints are defined within the paths section of the OpenAPI Specification (OAS) document. Each endpoint can support multiple HTTP methods (operations) such as GET, POST, PUT, DELETE, etc.
Example:
paths:
/items:
get:
summary: Retrieves a list of items
responses:
'200':
description: A list of items
content:
application/json:
schema:
type: array
items:
type: string
Let's breakdown the previous example:
The endpoint URL is:
/itemsThe endpoint operation is:
GETThe endpoint purpose is to retrieve a list of items.
The response code in case of a success response is:
200The response contains a list of items which is the purpose of this endpoint.
The type of the content of the response is
application/json.The response contains an array of string representing the items.
2. Defining Operations
Operations in Swagger correspond to HTTP methods such as GET, POST, PUT, DELETE, etc. And describe the action performed on an endpoint. Each operation can include details such as summary, description, parameters, request body, and responses.
Here's an example of an endpoint with path parameters and different responses:
- We'll explain each section in detail as we progress through the article.
paths:
/items/{itemId}:
get:
summary: Retrieve a specific item
description: Retrieve an item by its unique ID.
parameters:
- name: itemId
in: path
required: true
description: ID of the item to retrieve
schema:
type: integer
format: int64
responses:
'200':
description: A single item
content:
application/json:
schema:
type: object
properties:
id:
type: integer
format: int64
name:
type: string
description:
type: string
'404':
description: Item not found
3. Specifying Parameters
Parameters are inputs to an API operation. They can be defined in the path, query, header, or cookie. Each parameter can include:
name: Defines the name of the parameter.in: Indicates the location of the parameter, such asquery,path,header, orcookie.required: Specifies whether the parameter is mandatorytrueor optionalfalse.description: Provides a detailed explanation of the parameter and its purpose.schema: Describes the type and format of the parameter such as integer (int32), integer (int64), double, string, etc.
Path Parameters:
- A common mistake when adding a path parameter is forgetting to include the parameter in the endpoint URL. In our example, the endpoint URL should be written as
items/{itemId}.
parameters:
- name: itemId
in: path
required: true
description: ID of the item to retrieve
schema:
type: integer
format: int64
In the Swagger editor, it will appear as shown in the following image:
Query Parameters:
parameters:
- name: limit
in: query
required: false
description: The number of items to return
schema:
type: integer
format: int32
In the Swagger editor, it will appear as shown in the following image:
Header Parameters:
parameters:
- name: X-Request-ID
in: header
required: true
schema:
type: string
format: uuid
- In the Swagger editor, it will appear as shown in the following image:
Cookie Parameters:
parameters:
- name: csrftoken
in: cookie
schema:
type: string
- In the Swagger editor, it will appear as shown in the following image:
4. Defining Request Bodies
The request body is used to send data to the API. In Swagger, the request body is described using the requestBody section, which includes the content type and schema.
Additionally, using the request body can help hide sensitive data from being exposed as query or path parameters for security reasons.
Example:
requestBody:
description: Item to add to the database
required: true
content:
application/json:
schema:
type: object
properties:
name:
type: string
description:
type: string
- In the Swagger editor, it will appear as shown in the following image:
5. Specifying Responses
Responses define the possible outcomes of an API operation, including status codes and response bodies. Each response must include a description and may include a schema.
Example:
responses:
'200':
description: A single item
content:
application/json:
schema:
type: object
properties:
id:
type: integer
format: int64
name:
type: string
description:
type: string
'404':
description: Item not found
6. Using Swagger Editor to Define Endpoints and Operations
Steps:
Open Swagger Editor (locally or online).
Define the
pathssection and add endpoints.Add operations for each endpoint, including parameters, request bodies, and responses.
Validate the YAML file to ensure it follows the OpenAPI Specification.
Conclusion
Defining API endpoints and operations in Swagger ensures that your API is well-documented and easily understandable by both developers and non-developers. By specifying endpoints, operations, parameters, request bodies, and responses, you create a comprehensive and interactive API documentation.
In the next article, we'll start a practical tutorial to design an API step by step. This hands-on guide will walk you through each stage of the process, from defining endpoints to specifying parameters and responses. By the end of the tutorial, you'll have a solid understanding of how to create comprehensive and effective API documentation using Swagger.
Stay tuned for our next article, where we will put theory into practice and build a complete API documentation from scratch.