¿Cómo puedo usar overlays de OpenAPI para añadir metadatos de limitación de velocidad (rate limiting) a la descripción de una API? #

Las políticas de limitación de velocidad (rate limiting) se configuran con frecuencia en un API gateway (como Kong, Apigee o AWS API Gateway) en lugar de en el propio documento OpenAPI, lo que significa que los desarrolladores que leen la documentación a menudo no saben qué límites se aplican hasta que reciben un 429. Como los límites de velocidad no forman parte del vocabulario central de OpenAPI, los equipos suelen documentarlos mediante extensiones de proveedor, y la OpenAPI Overlay Specification es una forma limpia de añadir estos metadatos sin exigir que cada autor de la API recuerde incluirlos manualmente.

Definir una convención de extensión para los límites de velocidad #

Una estructura sencilla y coherente funciona bien en toda una API:

x-rate-limit:
  requestsPerMinute: 600
  burst: 50
  scope: "per-api-key"

Aplicar los metadatos de límites de velocidad mediante un overlay #

overlay: 1.0.0
info:
  title: Rate Limit Metadata Overlay
  version: 1.0.0
actions:
  - target: $.paths['/orders'].get
    update:
      x-rate-limit:
        requestsPerMinute: 600
        burst: 50
        scope: "per-api-key"
  - target: $.paths['/orders'].post
    update:
      x-rate-limit:
        requestsPerMinute: 120
        burst: 10
        scope: "per-api-key"

Documentar la respuesta 429 de forma coherente #

Junto con los metadatos de límites de velocidad, conviene asegurarse de que toda operación sujeta a limitación documente una respuesta 429 coherente:

  - target: $.paths['/orders'].get.responses
    update:
      "429":
        description: "Too Many Requests — rate limit exceeded. See the Retry-After header."
        headers:
          Retry-After:
            schema:
              type: integer
            description: "Number of seconds to wait before retrying."

Obtener los límites reales de la configuración del gateway #

En lugar de escribir a mano límites que pueden desviarse de lo que realmente se aplica, genera el overlay de forma programática a partir de la exportación de configuración de tu gateway. Por ejemplo, si usas Kong, un script puede leer la configuración del plugin rate-limiting de cada ruta y emitir las acciones de overlay correspondientes:

for (const route of kongRoutes) {
  actions.push({
    target: `$.paths['${route.path}'].${route.method.toLowerCase()}`,
    update: {
      'x-rate-limit': {
        requestsPerMinute: route.rateLimitingPlugin.minute,
        scope: 'per-api-key'
      }
    }
  });
}

Así, los límites documentados se mantienen sincronizados automáticamente con la configuración realmente aplicada, lo que elimina toda una categoría de informes de errores del tipo “la documentación es incorrecta”.

Mostrar los metadatos en la documentación #

Generadores de documentación como Redoc permiten mostrar campos x- arbitrarios con un poco de personalización del tema, o bien puedes transformar los metadatos en una tabla mediante los ganchos de plantillas de un generador de documentación, de modo que los límites de velocidad aparezcan de forma destacada junto a cada operación.

Aplicar el overlay #

redocly join openapi.yaml --overlay rate-limits-overlay.yaml -o dist/openapi.yaml

Lecturas relacionadas #

Consulta ¿Qué es la OpenAPI Overlay Specification? para conocer el modelo de acciones de los overlays, y ¿Cómo puedo usar overlays de OpenAPI para automatizar cambios en un pipeline de CI/CD? para ver cómo integrar en tu compilación scripts generadores como el anterior.

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