openapi-examples-generator: la nueva herramienta open source de APIAddicts Foundation para generar ejemplos en tus OpenAPI

En APIAddicts Foundation seguimos ampliando nuestro ecosistema de herramientas open source para el ciclo de vida de las APIs. Hoy presentamos openapi-examples-generator, una CLI que inyecta automáticamente ejemplos realistas en tus documentos OpenAPI/Swagger a partir de la estructura de sus esquemas. Si tu especificación tiene schemas pero no tiene example/examples, esta herramienta los genera por ti.

El problema: contratos sin ejemplos

Una definición OpenAPI sin ejemplos es un contrato a medias. Los ejemplos son la primera documentación que consume un desarrollador: alimentan el «Try it out» de Swagger UI y Redoc, permiten levantar mocks fieles (Prism, Microcks), sirven de base para tests de contrato y aceleran el onboarding de cualquier consumidor de la API. Sin embargo, escribirlos y mantenerlos a mano es tedioso: se olvidan en los endpoints nuevos, se desincronizan cuando cambia el esquema y rara vez cubren todos los parámetros, cabeceras y respuestas.

El resultado es conocido: specs técnicamente válidas pero pobres como documentación, y herramientas de developer portal que muestran cuerpos vacíos donde debería haber un payload de ejemplo.

Qué es openapi-examples-generator

openapi-examples-generator es una herramienta de línea de comandos, publicada por APIAddicts Foundation en GitHub, que recorre tu documento y rellena los ejemplos que faltan usando openapi-sampler (el motor de generación de Redocly) para producir valores coherentes con cada esquema.

  • Soporta Swagger 2.0, OpenAPI 3.0 y OpenAPI 3.1, tanto en YAML como en JSON.
  • Respeta los ejemplos escritos a mano: por defecto nunca sobrescribe un ejemplo existente (salvo que uses --force).
  • Preserva el formato, el orden y los comentarios del YAML original en todo lo que no toca.
  • Inyecta los ejemplos siempre en campos oficiales de la especificación, nunca como hermanos de un $ref (el clásico problema de que muchas herramientas ignoran lo que acompaña a un $ref).

Instalación en 30 segundos

git clone https://github.com/apiaddicts/openapi-examples-cli
cd openapi-examples-cli
npm install
npm link   # registra el comando openapi-examples

openapi-examples --version

Si prefieres no tocar el PATH global, puedes ejecutarla directamente con npx . <input> o con node bin/cli.js <input>.

Uso básico

# genera ejemplos in-place (sobrescribe el fichero de entrada)
openapi-examples swagger.yaml

# genera a otro fichero, dejando el original intacto
openapi-examples swagger.yaml -o swagger.examples.yaml

# regenera y sobrescribe también los ejemplos existentes
openapi-examples swagger.yaml --force

# fuerza el formato de salida
openapi-examples swagger.yaml --format json -o swagger.json

# log detallado de lo generado, saltado o avisado
openapi-examples swagger.yaml --verbose

El comportamiento por defecto es el mismo que eslint --fix: sin flags de salida, modifica el fichero de entrada.

Dónde se inyectan los ejemplos

La herramienta cubre las cuatro grandes zonas de una especificación, cada una desactivable con su flag:

  • Parámetros (--no-parameters): example en OpenAPI 3.x (incluidos los parámetros con content) y x-example en Swagger 2.0, que es lo que lee Swagger UI al no existir campo oficial en 2.0.
  • Request y response bodies (--no-request-body / --no-responses): content[mediaType].example en 3.x y response.examples[mime] en 2.0.
  • Cabeceras (--no-headers): cabeceras de respuesta y de encoding en multipart.
  • Propiedades de esquemas (--no-schema-examples): añade example a cada propiedad escalar de components.schemas/definitions y de los esquemas inline, de forma recursiva a través de objetos anidados, items de arrays y ramas allOf. Nunca pisa un ejemplo manual ni estampa un ejemplo global en el nodo raíz de un esquema reutilizable.

Como gate de CI: el flag –check

Una de las funciones más útiles para gobierno de APIs es el modo dry-run:

openapi-examples swagger.yaml --check

No escribe nada: devuelve exit code 0 si todo tiene ejemplo y exit code 1 con la lista de ubicaciones que carecen de él. Es un quality gate perfecto para pull requests — detecta endpoints nuevos sin ejemplos o ejemplos borrados por accidente — sin necesitar permisos de escritura en el repositorio.

Modo avanzado: –examples-list

Para OpenAPI 3.x, el flag --examples-list genera la forma plural y reutilizable: crea entradas en components.examples con nombres deterministas derivados del operationId (por ejemplo getPetById_Param_petId) y las referencia desde el punto de uso. Al ser deterministas, ejecutar la herramienta de nuevo actualiza la misma entrada en lugar de acumular duplicados. En documentos OpenAPI 3.1, las propiedades de esquema usan el array examples de JSON Schema 2020-12.

Limitaciones conocidas

El proyecto es transparente con lo que aún no cubre: no resuelve $ref externos (tampoco lo hace openapi-sampler), no soporta todavía $ref a parámetros o respuestas compartidas (los detecta y los salta con aviso), y las entradas huérfanas en components.examples tras cambiar de modo con --force no se limpian automáticamente. En todos los casos la CLI avisa y continúa en lugar de romper la ejecución.

Open source, como todo en APIAddicts

openapi-examples-generator se une a la familia de herramientas de APIAddicts Foundation para el diseño, la calidad y el gobierno de APIs. El código está disponible en github.com/apiaddicts/openapi-examples-cli — issues, ideas y pull requests son bienvenidos.

Pruébala en tu próxima spec: en un solo comando pasarás de un contrato «mudo» a una API documentada con ejemplos coherentes en cada parámetro, cabecera y respuesta.

Publicaciones Similares