¿Cómo puedo usar overlays de OpenAPI para marcar operaciones como obsoletas? #

Marcar una operación como obsoleta rara vez es una sola edición: normalmente implica activar el indicador deprecated, actualizar la descripción con una ruta de migración y, a veces, añadir un encabezado Sunset o una extensión personalizada que indique la fecha de retirada. Hacerlo de forma coherente en una especificación grande, sobre todo cuando la obsolescencia se planifica antes del cambio real en el código, encaja muy bien con la OpenAPI Overlay Specification.

El campo estándar deprecated #

OpenAPI ya define un campo booleano deprecated en las operaciones y en los esquemas. Un overlay puede activarlo sin modificar el documento orientado a la implementación:

overlay: 1.0.0
info:
  title: Q3 2026 Deprecation Overlay
  version: 1.0.0
actions:
  - target: $.paths['/v1/orders'].get
    update:
      deprecated: true
      description: "Deprecated: use GET /v2/orders instead. This endpoint will be removed on 2026-12-01."

Marcar como obsoleto un esquema completo #

Los esquemas completos pueden marcarse como obsoletos de la misma manera, lo cual resulta útil cuando una representación antigua se está sustituyendo por una nueva:

  - target: $.components.schemas.LegacyOrder
    update:
      deprecated: true
      description: "Deprecated in favor of the Order schema. Will be removed in a future major version."

Añadir una fecha de retirada (sunset) legible por máquinas #

Dado que el campo deprecated integrado en OpenAPI es solo un booleano, los equipos suelen añadir una extensión de proveedor con la fecha real de retirada para que las herramientas (y las advertencias de las bibliotecas de cliente generadas) puedan reaccionar a ella de forma programática:

  - target: $.paths['/v1/orders'].get
    update:
      x-sunset: "2026-12-01"
      x-deprecation-link: "https://developer.example.com/changelog/orders-v2-migration"

Marcar como obsoletas varias operaciones a la vez #

Si se va a retirar una versión completa de la API, los comodines de JSONPath permiten aplicar los mismos metadatos de obsolescencia a todas las operaciones bajo un prefijo de ruta en una sola acción, siempre que tus herramientas resuelvan el comodín según la estructura de tu documento:

  - target: $.paths['/v1/orders'].*
    update:
      deprecated: true
      x-sunset: "2026-12-01"

Verifica siempre el resultado combinado (merge); algunos procesadores de overlays requieren una acción por cada método HTTP en lugar de un comodín para todos los métodos, según la madurez de la implementación.

Preparar la obsolescencia con antelación #

Un patrón muy eficaz consiste en escribir el overlay de obsolescencia en cuanto se toma la decisión, mucho antes de la fecha real de retirada, y combinarlo (merge) con la documentación publicada «actual» solo cuando se alcance un feature flag o una fecha de lanzamiento. Así, la documentación y el registro de cambios de la API se mantienen perfectamente sincronizados con el calendario real de retirada.

Aplicar el overlay en CI #

redocly join openapi.yaml --overlay deprecations/2026-q3.yaml -o dist/openapi.yaml

Como los overlays de obsolescencia tienen fecha y están acotados a una versión concreta, guardarlos en una carpeta deprecations/ con nombres por trimestre o por versión te ofrece un historial de auditoría claro de qué se marcó como obsoleto y cuándo.

Lecturas relacionadas #

Consulta ¿Qué es la OpenAPI Overlay Specification? para conocer el mecanismo general, y ¿Cómo puedo usar overlays de OpenAPI para añadir avisos de obsolescencia y fechas de retirada (sunset)? para profundizar en cómo comunicar los calendarios de retirada a los consumidores.

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