¿Cómo puedo usar overlays de OpenAPI para gestionar la documentación de una API multiinquilino (multi-tenant)? #

En una plataforma SaaS multiinquilino (multi-tenant), no todos los inquilinos (tenants) tienen acceso al mismo conjunto de capacidades de la API. Los inquilinos del nivel Enterprise pueden tener acceso a endpoints de exportación masiva y a webhooks avanzados, mientras que los del nivel Starter ven una superficie más reducida. Mantener a mano un documento OpenAPI distinto para cada nivel se vuelve rápidamente insostenible a medida que cambian los planes y los feature flags. La OpenAPI Overlay Specification te permite expresar la documentación de cada nivel como un pequeño diff respecto a un único documento base con todas las funcionalidades.

Etiquetar las operaciones restringidas por nivel en el documento base #

paths:
  /exports/bulk:
    post:
      x-plan-tier: "enterprise"
      summary: Trigger a bulk data export
  /webhooks:
    get:
      x-plan-tier: "pro"
      summary: List configured webhooks
  /orders:
    get:
      x-plan-tier: "starter"
      summary: List orders

Overlay para el nivel Starter #

El overlay del nivel Starter elimina todo lo que esté por encima de su propio nivel:

overlay: 1.0.0
info:
  title: Starter Tier Documentation Overlay
  version: 1.0.0
actions:
  - target: $.paths['/exports/bulk']
    remove: true
  - target: $.paths['/webhooks']
    remove: true

Overlay para el nivel Pro #

overlay: 1.0.0
info:
  title: Pro Tier Documentation Overlay
  version: 1.0.0
actions:
  - target: $.paths['/exports/bulk']
    remove: true

Overlay para el nivel Enterprise #

El nivel Enterprise normalmente no necesita ninguna eliminación; en cambio, su overlay puede añadir contenido adicional, como los datos de contacto de soporte dedicado:

overlay: 1.0.0
info:
  title: Enterprise Tier Documentation Overlay
  version: 1.0.0
actions:
  - target: $.info
    update:
      description: "Full API access including bulk exports and webhook management, available on the Enterprise plan."

Generar overlays por nivel a partir de la configuración de planes #

Si tu sistema de facturación o de derechos de uso (entitlements) ya define qué valores de x-plan-tier corresponden a cada plan, un script puede generar automáticamente el overlay de “eliminar todo lo que esté por encima de mi nivel” en lugar de mantenerlo a mano:

const tierOrder = ['starter', 'pro', 'enterprise'];
const myTierIndex = tierOrder.indexOf(targetTier);

for (const [path, methods] of Object.entries(spec.paths)) {
  for (const [method, operation] of Object.entries(methods)) {
    const opTier = operation['x-plan-tier'] || 'starter';
    if (tierOrder.indexOf(opTier) > myTierIndex) {
      actions.push({ target: `$.paths['${path}'].${method}`, remove: true });
    }
  }
}

Compilar la documentación por nivel #

for tier in starter pro enterprise; do
  redocly join openapi.yaml --overlay "overlays/tier.overlay.$tier.yaml" -o "dist/openapi.$tier.yaml"
done

Cada inquilino, al visitar el portal de documentación, puede ser dirigido al documento generado que corresponda a su plan actual, de modo que nunca vea endpoints a los que en realidad no puede llamar.

Mantener sincronizados los derechos de uso y la documentación #

Como la lógica del overlay por nivel puede generarse directamente a partir de la misma configuración de entitlements que impulsa la autorización en tiempo de ejecución, la documentación y el acceso real a la API se mantienen alineados automáticamente cuando cambian los planes, sin necesidad de actualizar manualmente dos lugares distintos.

Lecturas relacionadas #

Consulta ¿Qué es la OpenAPI Overlay Specification? y ¿Cómo puedo usar overlays de OpenAPI para crear subconjuntos de API específicos para socios? para una técnica relacionada de delimitación por audiencia.

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