Swagger’s ability to display example request and response payloads is actually a powerful tool for validating your API’s design, not just documenting it.
Let’s see it in action. Imagine you’re defining an endpoint to fetch a user’s profile:
paths:
/users/{userId}:
get:
summary: Get user profile
parameters:
- name: userId
in: path
required: true
schema:
type: string
example: "a1b2c3d4-e5f6-7890-1234-567890abcdef"
responses:
'200':
description: User profile
content:
application/json:
schema:
type: object
properties:
id:
type: string
example: "a1b2c3d4-e5f6-7890-1234-567890abcdef"
username:
type: string
example: "jane_doe"
email:
type: string
example: "jane.doe@example.com"
isActive:
type: boolean
example: true
examples:
# Example 1: A typical user
user_active:
summary: Active User Profile
value:
id: "a1b2c3d4-e5f6-7890-1234-567890abcdef"
username: "jane_doe"
email: "jane.doe@example.com"
isActive: true
# Example 2: An inactive user
user_inactive:
summary: Inactive User Profile
value:
id: "f0e9d8c7-b6a5-4321-0987-654321fedcba"
username: "john_smith"
email: "john.smith@example.com"
isActive: false
'404':
description: User not found
content:
application/json:
schema:
type: object
properties:
message:
type: string
example: "User with ID 'non-existent-id' not found."
When rendered by a Swagger UI, this would present the user with an interactive documentation page. For the GET /users/{userId} endpoint, they’d see the userId parameter in the path. Crucially, they’d also see a "Examples" dropdown under the 200 OK response. Clicking "Active User Profile" would populate the response body with the JSON for jane_doe, while "Inactive User Profile" would show john_smith. The 404 response would also have its own example, demonstrating the error structure.
The real power here is that these examples aren’t just decorative. They serve as concrete instances of your API’s contract. You can use the example keyword directly within a schema property to define a single, default example for that specific field. For more complex or multiple examples for an entire response, you use the examples object under content. Each key in the examples object (like user_active or user_inactive) becomes a selectable example in the UI, and its value is the actual payload.
This forces you to think about what actual data looks like. It’s easy to define a schema like type: object with properties: { name: { type: string } }. But what kind of string? Is it a full name? A username? Does it contain spaces? Adding example: "Jane Doe" or example: "jane_doe" immediately clarifies this. For responses, having multiple, distinct examples for different scenarios (like an active vs. inactive user) exposes edge cases and clarifies behavioral variations that a simple schema definition might miss. You can even define examples for error responses, showing exactly what a client should expect when things go wrong.
The most surprising thing about using examples is how it flattens the distinction between documentation and testing. A client developer can take an example response directly from Swagger UI, modify the request example, and have a high degree of confidence that the structure will be correct, even before hitting your live API. This reduces the "it works on my machine" problem by providing a shared, concrete understanding of the data.
Beyond just showing what data looks like, the examples keyword can also be used to demonstrate how to request data, especially for complex query parameters or request bodies.
This capability is a crucial step towards building self-documenting and self-testing APIs.