OpenAPI Generator es una herramienta de código abierto que convierte una especificación OpenAPI o Swagger en código funcional: SDK de cliente, stubs de servidor y archivos de configuración. Se instala su CLI, se le apunta a la especificación, se elige un generador como typescript-axios o spring, y escribe el código en una carpeta de salida. Esta guía le muestra cómo instalarlo, listar los generadores disponibles y producir clientes y servidores para varios lenguajes.
Qué es OpenAPI Generator
OpenAPI Generator lee una descripción de API legible por máquina y emite código fuente a partir de ella. Se le proporciona un archivo openapi.yaml (o JSON) y puede generar una biblioteca cliente para llamar a esa API, un stub de servidor que la implementa, además de documentación y configuración.
Soporta tanto OpenAPI v2 (el formato Swagger más antiguo) como OpenAPI v3. El proyecto es mantenido por la organización OpenAPITools en GitHub, con plantillas para docenas de lenguajes y frameworks.
La distinción clave: es un generador de código, no un generador de documentación. Las herramientas de documentación como Swagger UI o Redoc renderizan su especificación en páginas HTML legibles por humanos. OpenAPI Generator, en cambio, produce código que se compila y distribuye. También puede emitir documentos Markdown, pero su trabajo principal son los SDK y los stubs.
Cómo se relaciona con Swagger Codegen
Si ha utilizado Swagger Codegen, OpenAPI Generator le resultará familiar. Fue bifurcado de Swagger Codegen en mayo de 2018, entre las versiones 2.3.1 y 2.4.0 de Swagger Codegen, por más de 40 de sus principales colaboradores y creadores de plantillas.
La bifurcación ocurrió después de un desacuerdo sobre la dirección de Swagger Codegen 3.0.0. La comunidad quería un ciclo de lanzamiento más rápido y abierto. Las notas oficiales de la bifurcación describen el proyecto como basado en Swagger Codegen 2.4.0-SNAPSHOT, por lo que los dos comparten raíces profundas. Si está sopesando ambos, el desglose de alternativas a Swagger Codegen cubre las diferencias prácticas.
Instalación de OpenAPI Generator
Tiene cuatro rutas de instalación comunes. Elija la que se adapte a su stack.
npm (más común)
El wrapper de npm es el punto de entrada más fácil para la mayoría de los equipos. Descarga y gestiona el JAR subyacente por usted.
npm install @openapitools/openapi-generator-cli -g
También puede ejecutarlo sin una instalación global:
npx @openapitools/openapi-generator-cli version
Homebrew (macOS)
brew install openapi-generator
JAR autónomo
OpenAPI Generator es una aplicación Java, por lo que puede descargar el JAR directamente desde Maven Central y ejecutarlo con Java. Esto evita por completo la capa de npm o Homebrew.
wget https://repo1.maven.org/maven2/org/openapitools/openapi-generator-cli/7.23.0/openapi-generator-cli-7.23.0.jar -O openapi-generator-cli.jar
java -jar openapi-generator-cli.jar help
Consulte Maven Central para conocer el número de versión más reciente antes de descargar.
Docker
La imagen oficial le permite generar código sin instalar nada localmente. Monte su directorio de trabajo en el contenedor para que pueda leer su especificación y escribir la salida.
docker pull openapitools/openapi-generator-cli
docker run --rm -v "${PWD}:/local" openapitools/openapi-generator-cli generate \
-i /local/openapi.yaml -g go -o /local/out/go
Listado de los generadores disponibles
Antes de generar cualquier cosa, vea qué generadores existen. Cada generador apunta a un lenguaje más un framework, como java, python o spring.
openapi-generator-cli list
Para una vista compacta, una por línea, use el indicador corto y divida por comas:
openapi-generator-cli list -s | tr ',' '\n'
La lista separa los generadores de cliente (para llamar a una API) de los generadores de servidor (para implementar una), además de los generadores de documentación y esquema.
Generación de un SDK de cliente
El comando principal es generate. Toma tres argumentos que usará cada vez:
-i, --input-specapunta a su archivo de especificación o URL.-g, --generator-nameselecciona qué generador ejecutar.-o, --outputestablece el directorio de salida.
Aquí hay un cliente TypeScript construido sobre Axios:
openapi-generator-cli generate -i openapi.yaml -g typescript-axios -o ./client
Eso escribe un cliente tipado en ./client. Cada operación en su especificación se convierte en un método, y cada esquema se convierte en un modelo.
El mismo patrón funciona en diferentes lenguajes. Intercambie el nombre del generador y la carpeta de salida:
openapi-generator-cli generate -i openapi.yaml -g java -o ./client-java
openapi-generator-cli generate -i openapi.yaml -g python -o ./client-python
openapi-generator-cli generate -i openapi.yaml -g go -o ./client-go
Debido a que el código proviene de una única especificación, cada cliente se mantiene consistente con el contrato. Cuando la especificación cambia, usted regenera y sus SDK la siguen.
Generación de stubs de servidor
Los generadores de servidor invierten la dirección. En lugar de código que llama a su API, obtiene un andamiaje que la implementa, con enrutamiento, modelos de solicitud e interfaces de controlador configuradas. Usted rellena la lógica de negocio.
openapi-generator-cli generate -i openapi.yaml -g spring -o ./server-spring
El proyecto generado le proporciona controladores y DTO que coinciden con su especificación. Usted implementa los métodos de la interfaz, y las formas de solicitud y respuesta ya están definidas para usted. Esto mantiene el servidor en ejecución alineado con el contrato publicado.
Configuración de la salida
La salida predeterminada rara vez es exactamente lo que desea. OpenAPI Generator le ofrece varios controles.
Propiedades adicionales
La mayoría de los generadores exponen opciones por lenguaje a través de --additional-properties (alias corto -p). Páselas como pares key=value delimitados por comas:
openapi-generator-cli generate -i openapi.yaml -g typescript-axios -o ./client \
--additional-properties=npmName=@acme/api-client,supportsES6=true,withSeparateModelsAndApi=true
Cada generador documenta sus propias propiedades, así que consulte la página del generador para obtener la lista completa de claves que acepta.
Un archivo de configuración
Cuando la línea de comandos se alarga, mueva las opciones a un archivo de configuración. Se admiten tanto JSON como YAML.
openapi-generator-cli generate -i openapi.yaml -g typescript-axios -o ./client -c config.yaml
Un archivo de configuración mantiene sus ajustes de generación en el control de versiones junto a la especificación, lo que hace que las compilaciones sean reproducibles.
Ignorando archivos
OpenAPI Generator lee un archivo .openapi-generator-ignore en el directorio de salida. Utiliza la misma sintaxis que .gitignore. Úselo para evitar que el generador sobrescriba los archivos que ha editado manualmente.
# .openapi-generator-ignore
*.md
src/custom/**
Puede apuntar a un archivo de ignorados en otra ubicación con --ignore-file-override <location>.
Plantillas personalizadas
Cada generador se basa en plantillas Mustache. Si la salida predeterminada no coincide con su estilo interno, copie las plantillas, edítelas y pase su directorio con -t:
openapi-generator-cli generate -i openapi.yaml -g typescript-axios -o ./client \
-t ./my-templates
Esta es la herramienta adecuada cuando necesita un encabezado personalizado, un cliente HTTP diferente o convenciones de nomenclatura internas incorporadas en cada archivo generado.
Ejecución en CI
La generación de código debe estar en su pipeline, no en el portátil de un desarrollador. Regenere el cliente con cada cambio de especificación para que el SDK comprometido nunca se desvíe del contrato. Aquí hay un paso de GitHub Actions usando npx:
- name: Generate API client
run: npx @openapitools/openapi-generator-cli generate -i openapi.yaml -g typescript-axios -o ./client
Puede hacer que la compilación falle si la salida regenerada difiere de lo que está comprometido, lo que detecta especificaciones y SDK que se han desincronizado.
Mantenga la especificación como su única fuente de verdad
OpenAPI Generator es tan bueno como la especificación que le proporciona. Si entra basura, sale basura: una especificación vaga o inválida produce un SDK vago o roto. Por lo tanto, el paso más valioso ocurre antes de ejecutar generate. Usted hace que la especificación sea correcta, completa y estable.
Aquí es donde Apidog encaja. Apidog es una plataforma API todo en uno que es nativa de OpenAPI, por lo que su trabajo de diseño y su especificación son el mismo artefacto. Usted diseña o importa la API, y Apidog mantiene el documento OpenAPI como la fuente de verdad de la que fluye todo lo demás.
Un flujo de trabajo limpio se ve así:
- Diseñe o importe la especificación OpenAPI en Apidog. El soporte de ramas le permite trabajar en cambios de forma aislada, similar al control de versiones de OpenAPI con Git.
- Valide y revise la especificación antes de generar. Una especificación que pasa un linter de OpenAPI y un validador de Swagger produce código más limpio con menos sorpresas.
- Exporte la especificación validada y luego proporciónesela a OpenAPI Generator para sus SDK y stubs.
También puede mantener la especificación sincronizada con su repositorio, por ejemplo, sincronizando la especificación OpenAPI con GitHub, y revisar los cambios con un diff de OpenAPI antes de que se implementen. Si está dejando herramientas más antiguas, la comparación de alternativas a Swagger para el diseño y las pruebas de API es un buen punto de partida.
Dónde termina Apidog y comienza OpenAPI Generator
Vale la pena ser precisos aquí. Apidog no genera SDK de cliente completos ni stubs de servidor. Ese es el trabajo de OpenAPI Generator, y ambos son complementarios en lugar de competidores.
Apidog le proporciona fragmentos de solicitud de cliente listos para copiar para cada endpoint, en muchos lenguajes y clientes HTTP. Son ejemplos por solicitud que puede pegar en un script, no un SDK empaquetado. Para una biblioteca generada y versionada o un andamiaje de servidor, ejecuta OpenAPI Generator en la especificación que produce Apidog.
Apidog también incluye su propio ejecutor de pruebas de línea de comandos, la CLI de Apidog, que es independiente de la generación de código. Ejecuta sus pruebas de API en CI; no genera SDK. Instálelo y úselo así:
npm install -g apidog-cli@latest
apidog run \
--access-token $APIDOG_ACCESS_TOKEN \
-t <testScenarioId> \
-e <envId> \
-r cli,html \
-n 1
Pasa la autenticación con --access-token, -t selecciona el escenario de prueba, -e elige el entorno contra el que ejecutar, y -r selecciona los reporteros. Ejecútelo en una versión LTS actual de Node.js. Para detalles de configuración, consulte la guía de instalación de Apidog CLI y el tutorial sobre pruebas de una API REST desde la línea de comandos.
Así, el ciclo completo es: diseñar y validar la especificación en Apidog, generar SDK y stubs con OpenAPI Generator, y luego verificar la API en ejecución con la CLI de Apidog.
Pruebe Apidog gratis, no se requiere tarjeta de crédito.
Preguntas Frecuentes
¿Qué es OpenAPI Generator?
OpenAPI Generator es una herramienta de código abierto de la organización OpenAPITools que genera código a partir de una especificación OpenAPI o Swagger. Produce SDK de cliente, stubs de servidor, documentación y archivos de configuración, y soporta tanto OpenAPI v2 como v3.
¿Cómo se usa OpenAPI Generator?
Instale la CLI (por ejemplo, npm install @openapitools/openapi-generator-cli -g), luego ejecute generate con tres indicadores: -i para su especificación, -g para el generador y -o para la carpeta de salida. Ejecute openapi-generator-cli list primero para ver todos los generadores disponibles.
¿Cómo funciona OpenAPI Generator?
Analiza su especificación en un modelo interno, luego renderiza ese modelo a través de plantillas Mustache para su objetivo elegido. Cada operación se convierte en un método o controlador, y cada esquema se convierte en un modelo tipado. Puede anular las plantillas con -t para cambiar la salida.
¿Cómo se genera un SDK de cliente a partir de una especificación OpenAPI?
Elija un generador de cliente y ejecute generate. Por ejemplo, openapi-generator-cli generate -i openapi.yaml -g typescript-axios -o ./client construye un cliente TypeScript tipado. Cambie typescript-axios por java, python o go para apuntar a otros lenguajes.
¿Cómo se generan stubs de servidor?
Elija un generador de servidor. Para un andamiaje de Spring Boot, ejecute openapi-generator-cli generate -i openapi.yaml -g spring -o ./server-spring. La salida incluye controladores y modelos de solicitud de su especificación, y usted implementa la lógica del controlador.
¿Cuál es la diferencia entre OpenAPI Generator y Swagger Codegen?
OpenAPI Generator fue bifurcado de Swagger Codegen en mayo de 2018 por más de 40 de sus colaboradores, quienes querían un ciclo de lanzamiento más rápido y impulsado por la comunidad. Los dos comparten una base común, pero OpenAPI Generator ahora tiene su propia hoja de ruta, conjunto de generadores y calendario de lanzamiento.
¿Cómo se genera un SDK de PHP a partir de una especificación OpenAPI?
Use el generador php: openapi-generator-cli generate -i openapi.yaml -g php -o ./client-php. Ejecute openapi-generator-cli list para confirmar el nombre exacto del generador y ver otras opciones de framework de PHP antes de generar.