Multiple responses
Document multiple response variations for API endpoints, including success and error cases, with status codes and example payloads.
If your API returns different responses based on input parameters, user context, or other conditions of the request, you can document multiple response examples with the examples property.
Add this property to any response. It has the following schema.
responses:
"200":
description: Successful response
content:
application/json:
schema:
$ref: "#/components/schemas/YourResponseSchema"
examples:
us:
summary: Response for United States
value:
countryCode: "US"
currencyCode: "USD"
taxRate: 0.0825
gb:
summary: Response for United Kingdom
value:
countryCode: "GB"
currencyCode: "GBP"
taxRate: 0.20The playground also handles non-JSON response types differently based on their content type.
Audio response examples
Section titled “Audio response examples”For endpoints that return audio files, set the response content type to audio/* and provide a URL to an audio file as the example value. The playground renders an interactive audio player instead of a code snippet.
responses:
"200":
description: Audio file generated successfully
content:
audio/mpeg:
schema:
type: string
format: binary
examples:
sample:
summary: Sample audio output
value: "https://example.com/sample-audio.mp3"