In our previous articles, we covered the basics of Swagger, defining API endpoints and operations, and creating schemas to promote reusability. In this article, we will focus on adding examples to your Swagger documentation. Examples are invaluable for helping users understand how to interact with your API by providing comprehensive instances of request and response data.
Why Examples Matter
Examples play a crucial role in API documentation for several reasons:
Clarity: They provide clear, concrete illustrations of how to use the API, making it easier for developers to understand the expected inputs and outputs.
Usability: Examples can demonstrate common use cases, helping users to quickly grasp how to implement the API in their applications.
Testing: Examples can be used as a basis for testing API endpoints, ensuring that the API behaves as expected.
Adding Examples to Your Swagger Documentation
In Swagger, you can add examples at various levels, including parameters, request bodies, and responses. Let’s walk through how to add examples to each of these components.
Adding Examples to Parameters
Parameters can have examples defined directly within their schema. Here’s how to add an example to a query parameter:
Example:
components:
parameters:
LimitParam:
name: limit
in: query
description: The number of items to return
required: false
schema:
type: integer
minimum: 1
example: 10
In this example, we define an example value of 10 for the limit query parameter.
Adding Examples to Request Bodies
Request bodies can include examples that demonstrate the structure and content of the data being sent to the API. Here’s an example of adding a request body with an example:
Example:
paths:
/items:
post:
summary: Add a new item
requestBody:
description: The item to add
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/Item'
example:
id: 123
name: "Sample Item"
description: "This is a sample item."
price: 19.99
responses:
'201':
description: The created item
content:
application/json:
schema:
$ref: '#/components/schemas/Item'
In this example, the request body includes an example of the Item schema with specific values for id, name, description, and price.
Adding Examples to Responses
Responses can also include examples to illustrate the data returned by the API. Here’s how to add an example to a response:
Example:
components:
responses:
ItemResponse:
description: A single item
content:
application/json:
schema:
$ref: '#/components/schemas/Item'
example:
id: 123
name: "Sample Item"
description: "This is a sample item."
price: 19.99
In this example, we define an ItemResponse that includes an example of the Item schema with specific values.
Combining Examples for a Complete Endpoint
Let’s combine everything we’ve learned into a complete example for an endpoint that retrieves a specific item by ID, includes a query parameter, and provides request and response examples.
Complete Example:
openapi: 3.0.0
info:
version: 1.0.0
title: Items API
description: API for managing a collection of items
servers:
- url: http://api.example.com/v1
components:
schemas:
Item:
type: object
properties:
id:
type: integer
format: int64
name:
type: string
description:
type: string
price:
type: number
format: float
required:
- id
- name
- price
parameters:
LimitParam:
name: limit
in: query
description: The number of items to return
required: false
schema:
type: integer
minimum: 1
example: 10
responses:
ItemResponse:
description: A single item
content:
application/json:
schema:
$ref: '#/components/schemas/Item'
example:
id: 123
name: "Sample Item"
description: "This is a sample item."
price: 19.99
paths:
/items/{itemId}:
get:
summary: Retrieve a specific item by ID
parameters:
- name: itemId
in: path
required: true
description: ID of the item to retrieve
schema:
type: integer
format: int64
example: 123
- $ref: '#/components/parameters/LimitParam'
responses:
'200':
$ref: '#/components/responses/ItemResponse'
'404':
description: The specified resource was not found
content:
application/json:
schema:
type: object
properties:
message:
type: string
example:
message: "Item not found"
Conclusion
Adding examples to your Swagger documentation significantly enhances its clarity and usability. By providing concrete instances of request and response data, you help developers better understand how to interact with your API and test its functionality. In this article, we explored how to add examples to parameters, request bodies, and responses, and demonstrated how to combine these elements into a complete endpoint example.
In the next article, we will explore how to use advanced schemas in Swagger to document arrays and nested objects. By using advanced schemas, you can create more detailed and maintainable API documentation. Proper use of arrays and nested objects ensures your documentation accurately reflects the complexity of your API, making it easier for developers to understand and use.
Stay tuned for the next article "Advanced Schemas in Swagger: Arrays and Nested Objects", and don’t forget to subscribe to our newsletter to receive the latest updates.