¿Cómo puedo usar overlays de OpenAPI para añadir avisos de obsolescencia y fechas de retirada (sunset)? #

Marcar una operación con deprecated: true indica a las herramientas que algo va a desaparecer, pero no le dice a un desarrollador cuándo, por qué ni qué usar en su lugar. Seguir la emergente convención del encabezado Sunset de la IETF (RFC 8594) junto con una documentación clara resulta mucho más útil, y este tipo de cambio de documentación sensible al tiempo es un excelente candidato para la OpenAPI Overlay Specification, ya que el período de aviso suele planificarse con mucha antelación a la retirada efectiva.

Estructurar un aviso de obsolescencia completo #

overlay: 1.0.0
info:
  title: Orders v1 Sunset Overlay
  version: 1.0.0
actions:
  - target: $.paths['/v1/orders'].get
    update:
      deprecated: true
      description: >
        **Deprecated.** This endpoint will be removed on 2026-12-01.
        Migrate to `GET /v2/orders`, which adds cursor-based pagination
        and consistent field naming. See the migration guide linked below.
      x-sunset-date: "2026-12-01"
      x-migration-guide: "https://developer.example.com/changelog/orders-v2-migration"

Documentar el encabezado Sunset en las respuestas #

Si tu API devuelve realmente un encabezado Sunset en los endpoints obsoletos, documéntalo para que los desarrolladores de clientes sepan que deben comprobarlo de forma programática:

  - target: $.paths['/v1/orders'].get.responses['200'].headers
    update:
      Sunset:
        description: "Date after which this endpoint will stop functioning, per RFC 8594."
        schema:
          type: string
          format: date
        example: "2026-12-01"

Preparar los avisos de obsolescencia antes de la fecha efectiva #

Un flujo de trabajo práctico consiste en redactar el overlay completo de obsolescencia en cuanto se confirma la decisión (a menudo con meses de antelación) y programar su aplicación a la documentación publicada en un momento concreto del calendario de lanzamientos, en lugar de esperar al día exacto en que se retira el endpoint:

# Applied starting the first day of the announced notice period
redocly join openapi.yaml --overlay deprecations/orders-v1-sunset.yaml -o dist/openapi.yaml

Intensificar el aviso a medida que se acerca la fecha #

Algunos equipos mantienen dos versiones del mismo overlay de obsolescencia: un aviso inicial “suave” y una versión más urgente que se aplica en los últimos 30 días antes de la retirada:

  - target: $.paths['/v1/orders'].get
    update:
      description: >
        **⚠ This endpoint will be removed in less than 30 days (2026-12-01).**
        Please migrate to `GET /v2/orders` immediately.

Eliminar el aviso automáticamente después de la retirada #

Una vez que pasa la fecha de retirada efectiva y la operación se elimina por completo del documento base, la acción correspondiente del overlay deja de tener efecto (porque su destino ya no existe). En ese momento, elimina el archivo de overlay obsoleto en el mismo cambio que suprime la operación, para que la carpeta deprecations/ represente únicamente los avisos que siguen activos.

Lecturas relacionadas #

Consulta ¿Qué es la OpenAPI Overlay Specification? y ¿Cómo puedo usar overlays de OpenAPI para marcar operaciones como obsoletas? para ver la versión más básica de esta técnica.

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