¿Cómo puedo usar overlays de OpenAPI para censurar (redact) campos sensibles de un documento OpenAPI? #

No todos los campos de un esquema de OpenAPI están pensados para el consumo público. Los identificadores internos, los campos de feature flags, los atributos cercanos a datos personales (PII) o los campos vinculados a funcionalidades aún no publicadas suelen tener que ocultarse en la documentación de cara al exterior, aunque sigan estando totalmente documentados de forma interna. La OpenAPI Overlay Specification convierte esto en un proceso declarativo y repetible, en lugar de una tarea de edición manual.

Marcar los campos sensibles en el documento base #

Una convención coherente, como una extensión x-sensitive: true en una propiedad, facilita identificar qué hay que censurar:

components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: string
        email:
          type: string
        internalRiskScore:
          type: number
          x-sensitive: true
        ssoProviderId:
          type: string
          x-sensitive: true

Eliminar una propiedad con un overlay #

La acción remove funciona sobre propiedades individuales de un esquema, no solo sobre rutas completas:

overlay: 1.0.0
info:
  title: Public Redaction Overlay
  version: 1.0.0
actions:
  - target: $.components.schemas.User.properties.internalRiskScore
    remove: true
  - target: $.components.schemas.User.properties.ssoProviderId
    remove: true

Censurar campos en todos los esquemas #

Si los campos sensibles comparten un nombre común en varios esquemas (por ejemplo, todos los esquemas tienen un campo internalNotes), un destino con comodín permite eliminarlos todos con una sola acción:

  - target: $.components.schemas.*.properties.internalNotes
    remove: true

Censurar encabezados de respuesta #

A veces la información sensible se filtra a través de los encabezados de respuesta en lugar del cuerpo. Los overlays también pueden eliminarlos:

  - target: $.paths['/users/{id}'].get.responses['200'].headers['X-Internal-Trace-Id']
    remove: true

Censurar valores de ejemplo sin eliminar el campo #

En ocasiones el campo debe permanecer (porque forma parte del contrato público), pero el valor de ejemplo usado en la documentación es sensible o poco realista. En ese caso, usa update para reemplazar el ejemplo en lugar de remove:

  - target: $.components.schemas.User.properties.email
    update:
      example: "jane.doe@example.com"

Comprobar que no se ha pasado nada por alto #

Después de aplicar un overlay de censura, ejecuta una búsqueda de texto en el resultado generado para localizar términos sensibles conocidos, como red de seguridad:

redocly join openapi.yaml --overlay redaction-overlay.yaml -o dist/public-openapi.yaml
grep -i "internalRiskScore\|ssoProviderId" dist/public-openapi.yaml && echo "REDACTION FAILED" || echo "OK"

Integrar esta comprobación en CI evita que un campo olvidado llegue en silencio a la documentación pública.

Lecturas relacionadas #

Consulta ¿Qué es la OpenAPI Overlay Specification? para conocer el modelo de acciones subyacente, y ¿Cómo puedo usar overlays de OpenAPI para eliminar endpoints internos antes de publicar la documentación? para ver el equivalente de esta técnica a nivel de endpoint.

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