¿Cómo puedo usar overlays de OpenAPI para inyectar extensiones de proveedor para la generación de SDK? #

Herramientas como openapi-generator y Speakeasy leen campos de extensión x- específicos de cada proveedor (vendor extensions) para controlar con precisión el aspecto de los SDK generados: nombres de métodos, agrupaciones de módulos, comportamiento de reintentos, utilidades de paginación y más. Estas extensiones solo tienen sentido para el generador de código y añaden ruido para quien simplemente lee el contrato de la API. La OpenAPI Overlay Specification te permite inyectarlas en el momento de la generación, manteniendo el documento canónico independiente del generador.

Por qué mantener la configuración del generador fuera de la especificación base #

Cada generador espera nombres y estructuras de extensión distintos. Si das soporte a varias cadenas de herramientas de SDK (por ejemplo, una para TypeScript y otra para Go), incluir todos los conjuntos de extensiones de proveedor directamente en el documento base genera desorden y acoplamiento con herramientas concretas. Un overlay por generador mantiene aislada cada responsabilidad.

Añadir sugerencias de nombres con x-codegen #

overlay: 1.0.0
info:
  title: TypeScript SDK Generator Overlay
  version: 1.0.0
actions:
  - target: $.paths['/users/{id}'].get
    update:
      operationId: "getUserById"
      x-codegen-request-body-name: "body"
  - target: $.components.schemas.User
    update:
      x-typescript-type: "UserRecord"

Controlar la agrupación de clientes con etiquetas #

Muchos generadores agrupan los métodos del cliente generado según las tags. Un overlay puede normalizar las etiquetas específicamente para la salida del SDK sin cambiar las etiquetas que se muestran en la documentación dirigida a personas:

  - target: $.paths['/orders'].*
    update:
      x-sdk-group: "OrdersClient"

Añadir sugerencias de paginación y reintentos #

Algunos generadores admiten estrategias personalizadas de paginación o reintentos mediante extensiones:

  - target: $.paths['/orders'].get
    update:
      x-pagination:
        style: "cursor"
        cursorParam: "pageToken"
        limitParam: "pageSize"
      x-retryable: true

Archivos de overlay por lenguaje #

Una estructura habitual mantiene un overlay por cada lenguaje de destino, ya que las convenciones de nombres y los modismos difieren:

overlays/
  sdk.overlay.typescript.yaml
  sdk.overlay.go.yaml
  sdk.overlay.python.yaml

Tu pipeline de compilación aplica el overlay correcto antes de invocar al generador de ese lenguaje:

redocly join openapi.yaml --overlay overlays/sdk.overlay.go.yaml -o build/openapi.go.yaml
openapi-generator-cli generate -i build/openapi.go.yaml -g go -o clients/go

Evitar colisiones con los overlays de documentación #

Si además mantienes un overlay centrado en la documentación (para ejemplos o textos localizados), aplica los overlays en un orden definido, o combina varios overlays de forma secuencial en el pipeline, de modo que las extensiones exclusivas del SDK nunca se filtren a la documentación pública, y viceversa.

Validar la salida del generador #

Como las extensiones de proveedor son opacas para los validadores estándar de OpenAPI, añade a tu pipeline una prueba de humo que ejecute realmente el generador sobre el documento con el overlay aplicado y confirme que el SDK se compila correctamente. Así se detectan errores tipográficos en los nombres de las extensiones o valores mal formados antes de que lleguen a una versión publicada.

Lecturas relacionadas #

Consulta ¿Qué es la OpenAPI Overlay Specification? para conocer el mecanismo base, y ¿Cómo puedo usar overlays de OpenAPI para renombrar operationIds y lograr coherencia en los SDK? para una técnica estrechamente relacionada.

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