¿Cómo puedo usar overlays de OpenAPI para añadir requisitos de seguridad a operaciones específicas? #

A veces los requisitos de seguridad deben cambiar de forma independiente de la lógica de negocio de la operación: un endpoint puede pasar de autenticación opcional a ámbitos (scopes) de OAuth obligatorios a medida que madura, o un documento específico para socios puede requerir una clave de API adicional además del token bearer estándar. La OpenAPI Overlay Specification te permite aplicar estos cambios como un overlay en lugar de editar directamente la definición de la operación.

Añadir un requisito de seguridad a una operación #

overlay: 1.0.0
info:
  title: Enforce OAuth Scopes Overlay
  version: 1.0.0
actions:
  - target: $.paths['/orders'].post
    update:
      security:
        - oauth2:
            - "orders:write"

Esto supone que el esquema oauth2 y sus ámbitos ya están declarados en components.securitySchemes en el documento base; el overlay únicamente asocia el requisito a la operación.

Añadir una clave de API adicional para integraciones con socios #

  - target: $.paths['/reports'].get
    update:
      security:
        - oauth2:
            - "reports:read"
          partnerApiKey: []

Declarar el propio esquema de seguridad mediante un overlay #

Si el esquema de seguridad debe introducirse solo para el documento de una audiencia concreta (por ejemplo, un esquema de clave de API exclusivo para socios que no debe aparecer en la especificación pública), añádelo también a components.securitySchemes mediante el overlay:

  - target: $.components.securitySchemes
    update:
      partnerApiKey:
        type: apiKey
        in: header
        name: X-Partner-Key

Hacer pública una operación (eliminar la seguridad) #

A veces un overlay debe ir en la dirección contraria: en un entorno de pruebas (sandbox) o de demostración, la seguridad puede relajarse por completo estableciendo un requisito de seguridad vacío:

  - target: $.paths['/public/status'].get
    update:
      security: []

Un arreglo (array) vacío anula explícitamente cualquier requisito de seguridad global y marca la operación como no autenticada en la salida de ese overlay concreto.

Despliegues progresivos de seguridad #

Cuando introduzcas gradualmente un nuevo requisito de autenticación, mantén un overlay de “estado futuro” que describa la postura de seguridad final y combínalo en una compilación de preproducción mucho antes de la fecha de paso a producción. Así, los equipos cliente pueden validar los nuevos requisitos antes de que el cambio se active en todas partes.

redocly join openapi.yaml --overlay security/oauth-rollout-2026-q4.yaml -o dist/openapi.staging.yaml

Validar los overlays de seguridad #

Los cambios de overlay relacionados con la seguridad merecen una revisión de código especialmente cuidadosa, ya que un error podría bloquear el acceso a consumidores legítimos o exponer una operación sin querer. Combina cualquier cambio de overlay de seguridad con una regla de linter (por ejemplo, una regla personalizada de Spectral) que haga fallar la compilación si alguna operación queda sin requisito de seguridad, salvo que esté incluida explícitamente en una lista de excepciones.

Lecturas relacionadas #

Consulta ¿Qué es la OpenAPI Overlay Specification? para conocer el modelo general, y ¿Cómo puedo usar overlays de OpenAPI para gestionar la documentación de una API multiinquilino? para ver un caso de uso relacionado con reglas de acceso específicas de cada inquilino.

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