Adding response examples in Swagger documentation is crucial for providing clarity to API users. By demonstrating expected outputs, developers can better understand how to interact with your API. This guide presents three diverse and practical examples of adding response examples in Swagger documentation, ensuring that your APIs are well-documented and user-friendly.
In a typical application, an endpoint may be used to retrieve user profile information. Adding a response example not only helps developers understand the structure of the response but also showcases the data they can expect.
paths:
/users/{id}:
get:
summary: Retrieve a user profile
parameters:
- name: id
in: path
required: true
description: The ID of the user to retrieve
schema:
type: integer
responses:
'200':
description: A user profile object
content:
application/json:
schema:
type: object
properties:
id:
type: integer
example: 1
name:
type: string
example: "John Doe"
email:
type: string
example: "john.doe@example.com"
examples:
userProfile:
summary: Example user profile
value:
id: 1
name: "John Doe"
email: "john.doe@example.com"
This example provides a clear structure for the user profile response, allowing users to see both the data types and a sample output. Variations can include additional fields such as phone numbers or addresses, depending on the requirements of your application.
When an order is created in an e-commerce application, it’s essential to return a response that confirms the details of the order. Adding a response example assists developers in understanding the order structure.
paths:
/orders:
post:
summary: Create a new order
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
productId:
type: integer
quantity:
type: integer
responses:
'201':
description: Order successfully created
content:
application/json:
schema:
type: object
properties:
orderId:
type: integer
example: 101
status:
type: string
example: "Processed"
totalAmount:
type: number
format: float
example: 59.99
examples:
orderResponse:
summary: Example order creation response
value:
orderId: 101
status: "Processed"
totalAmount: 59.99
This example illustrates the order creation response, providing clarity on the expected fields. You can customize this by adding more details such as estimated delivery times or payment status, depending on your business needs.
In a scenario where users can search for products, providing an example of the response can help front-end developers understand how to parse the data effectively.
paths:
/products/search:
get:
summary: Search for products
parameters:
- name: query
in: query
required: true
description: The search term to filter products
schema:
type: string
responses:
'200':
description: A list of products matching the search term
content:
application/json:
schema:
type: object
properties:
products:
type: array
items:
type: object
properties:
id:
type: integer
example: 1
name:
type: string
example: "Wireless Mouse"
price:
type: number
format: float
example: 29.99
examples:
productSearchResponse:
summary: Example product search response
value:
products:
- id: 1
name: "Wireless Mouse"
price: 29.99
- id: 2
name: "Mechanical Keyboard"
price: 49.99
This example demonstrates a structured response for a product search, showcasing an array of products. Adjustments can be made to include pagination details or additional filtering options based on user search criteria.
By incorporating these examples into your Swagger documentation, you enhance the usability and clarity of your API, promoting a better developer experience.