Respuestas múltiples
Documenta múltiples variaciones de respuestas para endpoints de la API, incluyendo casos de éxito y error, con códigos de estado y payloads de ejemplo.
Si tu API devuelve respuestas diferentes según los parámetros de entrada, el contexto del usuario u otras condiciones de la solicitud, puedes documentar múltiples ejemplos de respuestas con la propiedad examples.
Agrega esta propiedad a cualquier respuesta. Tiene el siguiente esquema.
responses:
"200":
description: Respuesta exitosa
content:
application/json:
schema:
$ref: "#/components/schemas/YourResponseSchema"
examples:
us:
summary: Respuesta para Estados Unidos
value:
countryCode: "US"
currencyCode: "USD"
taxRate: 0.0825
gb:
summary: Respuesta para Reino Unido
value:
countryCode: "GB"
currencyCode: "GBP"
taxRate: 0.20El playground también maneja de forma diferente los tipos de respuesta que no son JSON según su tipo de contenido.
Para los endpoints que devuelven archivos de audio, establece el tipo de contenido de la respuesta en audio/* y proporciona la URL de un archivo de audio como valor de ejemplo. El playground muestra un reproductor de audio interactivo en lugar de un fragmento de código.
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"