¿Cómo puedo usar overlays de OpenAPI para renombrar operationIds y lograr coherencia en los SDK? #

El campo operationId determina directamente el nombre del método generado en la mayoría de los generadores de SDK de cliente. Cuando un documento OpenAPI se ha construido de forma incremental por varios equipos, los valores de operationId suelen acabar siendo inconsistentes: algunos empiezan por el verbo, otros por el recurso y otros están abreviados. Renombrarlos en bloque en el documento canónico puede ser arriesgado si otras herramientas (enrutamiento, telemetría, pruebas de contrato) ya dependen de los valores existentes. La OpenAPI Overlay Specification ofrece una vía más segura: renombrar operationId solo en la copia que se usa para generar los SDK.

Identificar nombres inconsistentes #

paths:
  /users/{id}:
    get:
      operationId: fetchUser
  /orders:
    get:
      operationId: list_orders
    post:
      operationId: OrdersCreate

Tres convenciones de nomenclatura distintas en tres operaciones producirán un SDK inconsistente y con aspecto poco pulido.

Normalizar con un overlay #

overlay: 1.0.0
info:
  title: SDK OperationId Normalization Overlay
  version: 1.0.0
actions:
  - target: $.paths['/users/{id}'].get
    update:
      operationId: "getUser"
  - target: $.paths['/orders'].get
    update:
      operationId: "listOrders"
  - target: $.paths['/orders'].post
    update:
      operationId: "createOrder"

Establecer una convención de nomenclatura a partir de ahora #

Documenta la convención que aplica tu overlay (por ejemplo, camelCase empezando por el verbo: get, list, create, update, delete seguido del nombre del recurso) para que las futuras entradas del overlay se mantengan coherentes a medida que se añadan nuevas operaciones.

Automatizar el renombrado con un script #

En las API grandes, escribir a mano decenas de acciones de renombrado es tedioso. Un script breve puede leer el documento base, aplicar una transformación según la convención de nomenclatura y generar el archivo del overlay automáticamente:

const yaml = require('js-yaml');
const fs = require('node:fs');

const spec = yaml.load(fs.readFileSync('openapi.yaml', 'utf8'));
const actions = [];

for (const [path, methods] of Object.entries(spec.paths)) {
  for (const [method, operation] of Object.entries(methods)) {
    const normalized = normalizeOperationId(method, path);
    if (operation.operationId !== normalized) {
      actions.push({
        target: `$.paths['${path}'].${method}`,
        update: { operationId: normalized }
      });
    }
  }
}

fs.writeFileSync('sdk-naming-overlay.yaml', yaml.dump({
  overlay: '1.0.0',
  info: { title: 'SDK OperationId Normalization Overlay', version: '1.0.0' },
  actions
}));

Aplicar el overlay antes de la generación #

redocly join openapi.yaml --overlay sdk-naming-overlay.yaml -o build/openapi.sdk.yaml
openapi-generator-cli generate -i build/openapi.sdk.yaml -g typescript-fetch -o clients/typescript

Mantener intacto el documento canónico #

Como la configuración de enrutamiento, las pruebas de contrato y los paneles de telemetría pueden hacer ya referencia a los valores originales de operationId, dejar el documento base sin cambios evita una migración mucho mayor y más arriesgada en sistemas no relacionados. El overlay limita el alcance del renombrado únicamente a la generación de los SDK.

Lecturas relacionadas #

Consulta ¿Qué es la OpenAPI Overlay Specification? y ¿Cómo puedo usar overlays de OpenAPI para inyectar extensiones de proveedor para la generación de SDK? para conocer otras técnicas relacionadas con las herramientas de SDK.

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