¿Cómo puedo usar overlays de OpenAPI para aplicar branding de marca blanca (white label) a la documentación de una API? #

Las plataformas que operan con un modelo de marca blanca (white label) o de reventa suelen exponer la misma API subyacente bajo varios nombres de marca, cada una con su propio dominio, nombre de producto y contacto de soporte. Mantener a mano un documento OpenAPI distinto para cada marca duplica el esfuerzo y garantiza que se desincronicen a medida que la API evoluciona. La OpenAPI Overlay Specification permite generar la documentación de cada marca a partir de una única especificación canónica con un pequeño overlay específico para cada una.

Qué suele cambiar según la marca #

• info.title e info.description
• info.contact e info.termsOfService
• servers (dominios personalizados de cada marca)
• Las referencias al nombre del producto dentro de los resúmenes y las descripciones de las operaciones

Un ejemplo de overlay de marca #

overlay: 1.0.0
info:
  title: "Acme Reseller Branding Overlay"
  version: 1.0.0
actions:
  - target: $.info
    update:
      title: "Acme Connect API"
      description: "The Acme Connect API lets you manage orders and customers programmatically."
      contact:
        name: "Acme Connect Support"
        email: "support@acmeconnect.example"
        url: "https://acmeconnect.example/support"
      termsOfService: "https://acmeconnect.example/terms"
  - target: $
    update:
      servers:
        - url: "https://api.acmeconnect.example/v1"
          description: "Acme Connect production environment"

Cambiar la marca en los textos a nivel de operación #

Si el nombre de tu producto aparece dentro de las descripciones de operaciones concretas, apunta a ellas de forma específica:

  - target: $.paths['/orders'].get
    update:
      description: "List all orders placed through the Acme Connect API."

Estructurar los overlays para muchas marcas #

Para plataformas que dan soporte a decenas de socios de marca blanca, resulta mucho más escalable almacenar los overlays como pequeños archivos YAML estructurados por marca, generados a partir de un archivo de configuración de socios ligero en lugar de escribirlos a mano para cada marca:

overlays/
  brand.overlay.acme.yaml
  brand.overlay.contoso.yaml
  brand.overlay.globex.yaml

Un script de generación puede leer una configuración brands.json que contenga únicamente los valores específicos de cada marca (nombre, dominio, correo de soporte) y generar el YAML del overlay a partir de una plantilla de forma automática, en lugar de exigir que una persona edite a mano 30 archivos casi idénticos.

Compilar la documentación de cada marca #

for brand in acme contoso globex; do
  redocly join openapi.yaml --overlay "overlays/brand.overlay.$brand.yaml" -o "dist/openapi.$brand.yaml"
  redocly build-docs "dist/openapi.$brand.yaml" -o "dist/docs/$brand/index.html"
done

El portal de documentación de cada marca se despliega a partir de su propio HTML generado, sin ninguna duplicación manual del contrato de la API subyacente.

Mantener un comportamiento funcional idéntico #

Como el overlay solo modifica metadatos de presentación (info, servers, descripciones textuales) y nunca elementos estructurales (rutas, esquemas, parámetros), todas las marcas siguen siendo funcionalmente idénticas por debajo; solo cambia la presentación, lo que evita el riesgo de introducir por accidente errores de comportamiento específicos de una marca.

Lecturas relacionadas #

Consulta ¿Qué es la OpenAPI Overlay Specification? para conocer el mecanismo general, y ¿Cómo puedo usar overlays de OpenAPI para gestionar documentación de API multiinquilino (multi-tenant)? para ver un patrón relacionado centrado en el acceso específico de cada inquilino en lugar del branding.

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