¿Cómo puedo usar overlays de OpenAPI para añadir ejemplos a un documento OpenAPI existente? #

Una buena documentación de API depende en gran medida de ejemplos realistas de solicitudes y respuestas, pero redactarlos suele ser un trabajo distinto del diseño del propio esquema. En lugar de saturar tu documento OpenAPI canónico con cargas útiles de ejemplo en cuanto se escriben, puedes mantenerlas en un archivo dedicado de la Overlay Specification y combinarlas únicamente al generar la documentación.

Por qué separar los ejemplos del documento base #

Los equipos suelen iterar sobre los ejemplos de la documentación mucho más rápido que sobre el esquema subyacente. Mantener los ejemplos en un overlay:

• Permite que redactores y developer advocates actualicen los ejemplos sin tocar el contrato de la API.
• Permite usar distintos conjuntos de ejemplos para distintas audiencias (por ejemplo, ejemplos de “inicio rápido” frente a ejemplos exhaustivos de casos límite).
• Mantiene las pull requests sobre la especificación base centradas en el propio contrato.

Apuntar a los cuerpos de respuesta y de solicitud #

La acción update realiza una combinación profunda (al estilo de RFC 7396), por lo que puedes añadir una clave examples sin alterar el resto del esquema:

overlay: 1.0.0
info:
  title: Add Documentation Examples
  version: 1.0.0
actions:
  - target: $.paths['/users/{id}'].get.responses['200'].content['application/json']
    update:
      examples:
        default:
          summary: A typical user record
          value:
            id: "usr_9F82"
            name: "Ada Lovelace"
            email: "ada@example.com"
            createdAt: "2026-01-15T10:00:00Z"

Añadir ejemplos a los cuerpos de solicitud #

El mismo patrón se aplica al contenido de requestBody:

  - target: $.paths['/orders'].post.requestBody.content['application/json']
    update:
      examples:
        minimal:
          summary: Minimal valid order
          value:
            productId: "prod_123"
            quantity: 1
        withNotes:
          summary: Order with optional notes
          value:
            productId: "prod_123"
            quantity: 2
            notes: "Gift wrap please"

Añadir varios ejemplos con nombre por operación #

El objeto examples de OpenAPI admite varios ejemplos con nombre por tipo de medio, lo que resulta ideal para mostrar tanto el “camino feliz” como uno o más casos límite:

  - target: $.paths['/payments'].post.responses['422'].content['application/json']
    update:
      examples:
        insufficientFunds:
          summary: Card declined due to insufficient funds
          value:
            error: "insufficient_funds"
            message: "The card was declined."
        expiredCard:
          summary: Expired card
          value:
            error: "expired_card"
            message: "The card has expired."

Apuntar a muchas operaciones a la vez #

Si quieres añadir un ejemplo genérico a todas las respuestas 404 de todo el documento, la compatibilidad de JSONPath con los comodines lo hace muy conciso:

  - target: $.paths.*.*.responses['404'].content['application/json']
    update:
      examples:
        notFound:
          summary: Resource not found
          value:
            error: "not_found"
            message: "The requested resource could not be located."

Ten en cuenta que la compatibilidad con comodines en combinaciones profundamente anidadas puede variar entre implementaciones de overlays, así que valida siempre el resultado con tus herramientas antes de publicar.

Aplicar el overlay #

redocly join openapi.yaml --overlay examples-overlay.yaml -o openapi.with-examples.yaml

El documento resultante puede pasarse directamente a un generador de documentación como Redoc o Swagger UI, ya que ambos muestran de forma destacada el objeto examples.

Mantener los ejemplos sincronizados #

Dado que el esquema base y el overlay de ejemplos son archivos independientes, añade un paso de validación en CI que compruebe cada ejemplo con su esquema correspondiente (muchos linters, incluido Spectral, lo admiten). Así evitas que el overlay se desfase silenciosamente a medida que evoluciona el esquema.

Lecturas relacionadas #

Consulta ¿Qué es la OpenAPI Overlay Specification? para conocer el modelo completo de acciones, y ¿Cómo puedo usar overlays de OpenAPI para enriquecer esquemas con reglas de validación adicionales? para ver una técnica relacionada.

Última actualización: 16 de julio de 2026.