¿Cómo puedo usar overlays de OpenAPI para crear subconjuntos de una API específicos para cada socio? #

Al incorporar socios de integración, es habitual concederles acceso solo a un puñado de endpoints relevantes para su integración concreta: un socio de pagos quizá solo necesite los endpoints de pedidos y reembolsos, mientras que un socio de logística necesita los de envío y seguimiento. Elaborar a mano un documento OpenAPI distinto para cada socio duplica el esfuerzo y se desincroniza a medida que evoluciona la API principal. La OpenAPI Overlay Specification permite definir el subconjunto de cada socio como un overlay pequeño y explícito en lugar de un documento bifurcado.

El enfoque de lista de permitidos: eliminar todo lo que no se necesita #

Como los overlays se adaptan mejor a eliminaciones y actualizaciones puntuales que a expresar “conserva solo esto”, el patrón más fiable consiste en eliminar explícitamente todo lo que el socio no debe ver:

overlay: 1.0.0
info:
  title: Payments Partner Subset Overlay
  version: 1.0.0
actions:
  - target: $.paths['/shipping']
    remove: true
  - target: $.paths['/tracking/{id}']
    remove: true
  - target: $.paths['/inventory']
    remove: true

Generar la lista de eliminaciones de forma programática #

En API con muchos endpoints, mantener una “lista de elementos a conservar” explícita para cada socio y generar automáticamente el overlay de eliminación correspondiente escala mucho mejor que escribir a mano decenas de acciones remove:

const keepForPaymentsPartner = ['/orders', '/orders/{id}', '/refunds'];
const actions = [];

for (const path of Object.keys(spec.paths)) {
  if (!keepForPaymentsPartner.includes(path)) {
    actions.push({ target: `$.paths['${path}']`, remove: true });
  }
}

Esto cambia el modelo mental de “recordar qué eliminar” a “declarar qué conservar”, sin dejar de producir por debajo un archivo de overlay estándar.

Reducir también los esquemas junto con las rutas #

Al eliminar rutas pueden quedar componentes de esquema que el socio tampoco debería ver (ni siquiera como documentación). Incluye también la eliminación de esquemas en el mismo overlay:

  - target: $.components.schemas.ShippingLabel
    remove: true
  - target: $.components.schemas.WarehouseLocation
    remove: true

Añadir requisitos de seguridad específicos de cada socio #

Los subconjuntos para socios suelen combinarse de forma natural con un esquema de seguridad dedicado, limitado a las credenciales de ese socio:

  - target: $.paths['/orders'].get
    update:
      security:
        - partnerApiKey: []

Estructurar los overlays por socio #

overlays/
  partner.overlay.payments-co.yaml
  partner.overlay.logistics-co.yaml

Compilar y entregar las especificaciones para socios #

redocly join openapi.yaml --overlay overlays/partner.overlay.payments-co.yaml -o dist/openapi.payments-co.yaml

El documento resultante puede entregarse directamente al socio (como una especificación descargable) o usarse para generar un portal de documentación específico para él, sin exponer en ningún caso capacidades que queden fuera del alcance de ese acuerdo de integración.

Lecturas relacionadas #

Consulta ¿Qué es la OpenAPI Overlay Specification? y ¿Cómo puedo usar overlays de OpenAPI para generar documentación de API específica para cada audiencia? para conocer el patrón más amplio de múltiples audiencias al que pertenece esta técnica.

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