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.20

The playground also handles non-JSON response types differently based on their content type.

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"