¿Cómo puedo usar overlays de OpenAPI para actualizar las URL de los servidores en distintos entornos? #

El bloque servers de un documento OpenAPI indica a las herramientas, y a los desarrolladores, adónde enviar realmente las solicitudes. También es una de las partes más específicas de cada entorno de todo el documento: el desarrollo local puede apuntar a http://localhost:3000, staging a un dominio de staging dedicado y producción al host real de la API, a veces con variantes regionales adicionales. La OpenAPI Overlay Specification ofrece una forma limpia de intercambiar este bloque por entorno sin mantener copias separadas de todo el documento.

Por qué servers merece un tratamiento especial #

A diferencia de la mayoría de los destinos de un overlay, servers es un arreglo (array), y en la mayoría de las implementaciones la acción update realiza un merge en lugar de un parche inteligente elemento por elemento. En la práctica, esto significa que el enfoque más seguro y predecible es reemplazar el arreglo completo en lugar de intentar modificar una sola de sus entradas.

Overlay para desarrollo local #

overlay: 1.0.0
info:
  title: Local Development Servers Overlay
  version: 1.0.0
actions:
  - target: $
    update:
      servers:
        - url: "http://localhost:3000"
          description: "Local development server"

Overlay para staging #

overlay: 1.0.0
info:
  title: Staging Servers Overlay
  version: 1.0.0
actions:
  - target: $
    update:
      servers:
        - url: "https://staging-api.example.com/v1"
          description: "Staging environment"

Overlay para producción multirregión #

Es posible que producción necesite listar varios endpoints regionales a la vez:

overlay: 1.0.0
info:
  title: Production Multi-Region Servers Overlay
  version: 1.0.0
actions:
  - target: $
    update:
      servers:
        - url: "https://api.us.example.com/v1"
          description: "US production region"
        - url: "https://api.eu.example.com/v1"
          description: "EU production region"
        - url: "https://api.apac.example.com/v1"
          description: "APAC production region"

Usar variables de servidor en lugar de varios overlays #

Si tus herramientas y generadores admiten las variables de servidor nativas de OpenAPI, un único overlay puede parametrizar el entorno en lugar de mantener un overlay por entorno:

  - target: $
    update:
      servers:
        - url: "https://{environment}-api.example.com/v1"
          variables:
            environment:
              default: "staging"
              enum: ["dev", "staging", "api"]

Esto sacrifica algo de la simplicidad del overlay a cambio de un resultado único más flexible, y funciona bien cuando el mismo portal de documentación debe permitir que el desarrollador elija de forma interactiva su entorno de destino.

Integrarlo en el proceso de compilación #

for env in local staging production; do
  redocly join openapi.yaml --overlay "overlays/servers.overlay.$env.yaml" -o "dist/openapi.$env.yaml"
done

Validar el resultado #

Dado que un error en el overlay de servers puede hacer que un SDK generado apunte en silencio al host equivocado, añade una comprobación automatizada tras aplicar el overlay que verifique que la URL esperada aparece en la salida:

grep -q "https://api.us.example.com/v1" dist/openapi.production.yaml || (echo "Production server URL missing!" && exit 1)

Lecturas relacionadas #

Consulta ¿Qué es la OpenAPI Overlay Specification? y ¿Cómo puedo usar overlays de OpenAPI para personalizar la documentación por entorno (dev/staging/prod)? para conocer el patrón más amplio de documentación específica por entorno.

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