El diseño de la API se realiza en su archivo de especificación mucho antes de que se envíe cualquier código. Una regla de estilo que olvide, un cambio importante que pase por alto, un esquema que se desvíe de lo que envió la semana pasada; todo esto cuesta más arreglarlo después. La línea de comandos detecta estos problemas donde comienzan, y lo hace en CI sin que nadie haga clic en una interfaz de usuario.
Este artículo trata sobre el lado de código abierto de esa cadena de herramientas. Cada herramienta aquí tiene código fuente disponible bajo una licencia permisiva, es gratuita de ejecutar sin costo por asiento, y algo que puede autoalojar o fijar a una versión que usted controla. Eso importa cuando el diseño de su API reside en un repositorio de Git y quiere que las comprobaciones se ejecuten de la misma manera en cada portátil y en cada pipeline. Si desea una visión más amplia de cómo encajan estas herramientas, comience con nuestra guía sobre cómo diseñar una API, luego regrese aquí para elegir las CLI.
Obtendrá seis herramientas, cada una con un comando de instalación real y el comando que muestra su funcionamiento: un linter para reglas de estilo, una alternativa rápida basada en Go, un empaquetador que también valida, un generador de código y documentación, y dos herramientas para detectar cambios importantes entre versiones de especificación. La Especificación OpenAPI es el lenguaje común que todos ellos hablan, por lo que una especificación que linted con una herramienta se alimenta limpiamente a la siguiente.
Una nota honesta de antemano. Apidog se presenta aquí, pero no es de código abierto; es un producto comercial con un nivel gratuito, y no lint su especificación. Así que recibe un aparte preciso, no una entrada de código abierto. Las herramientas a continuación son la verdadera cadena de herramientas de diseño de código abierto.
Qué hace que una herramienta CLI sea de código abierto para el diseño de API
Código abierto es una afirmación específica, no una sensación. Para esta lista, una herramienta califica cuando se cumplen tres cosas.
Primero, la licencia. Debe ser una licencia permisiva o copyleft real que pueda leer; MIT y Apache-2.0 son las dos que verá con más frecuencia aquí. Eso es lo que le permite usar la herramienta en un proyecto comercial sin una tarifa de licencia ni un recuento de asientos.
Segundo, autoalojamiento y control de versiones. Puede vender el binario, fijar una versión exacta y ejecutarlo completamente sin conexión en un ejecutor de CI aislado. Ninguna herramienta aquí llama a casa o necesita una cuenta para hacer su trabajo principal.
Tercero, mantenimiento y comunidad. Un repositorio con commits recientes, problemas abiertos que obtienen respuestas y un registro de cambios público. Un proyecto abandonado aún puede tener licencia MIT y seguir siendo una mala apuesta, así que señalo el estado de mantenimiento donde importa.
Cada herramienta a continuación se verifica contra esos tres puntos. Donde un proyecto está inactivo, lo verá señalado.
Spectral: el linter de estilo OpenAPI flexible
Spectral de Stoplight es el linter de código abierto de referencia para descripciones de API, con licencia Apache-2.0. Lee un conjunto de reglas (un archivo YAML, JSON o JavaScript que lista sus reglas) y lo aplica a documentos OpenAPI 3.x, OpenAPI 2.0, AsyncAPI y Arazzo. Si su equipo tiene una guía de estilo de API escrita, Spectral es la forma de hacerla ejecutable.
npm install -g @stoplight/spectral-cli
spectral lint openapi.yaml
De serie, viene con un conjunto de reglas `oas` que marca descripciones faltantes, ejemplos inválidos y problemas estructurales. El verdadero valor aparece en las reglas personalizadas: requerir un `operationId` en cada operación, un esquema compartido en las respuestas de error, una convención de nomenclatura en las rutas. Esas reglas viven en su repositorio y se ejecutan idénticamente para cada colaborador.
Lo mejor para: hacer cumplir una guía de estilo de equipo como código. Límite honesto: Spectral verifica una sola especificación; no compara dos versiones, así que combínelo con una herramienta de diferencias para detectar cambios importantes.
vacuum: el linter más rápido, de reemplazo directo para los conjuntos de reglas de Spectral
Si Spectral es el estándar, vacuum es la opción de velocidad. Es un linter de Go, con licencia MIT, 100% compatible con los conjuntos de reglas de Spectral. Así que puede apuntarlo al mismo conjunto de reglas que ya escribió y obtener resultados mucho más rápido en especificaciones grandes, que es exactamente lo que desea en un hook de pre-commit o un ciclo de CI ajustado.
brew install --cask daveshanley/vacuum/vacuum
vacuum lint -d openapi.yaml
La bandera `-d` le da una salida detallada por regla. vacuum también hace más que lint; genera informes HTML y documentación a partir de la misma especificación. Debido a que es un solo binario compilado sin entorno de ejecución de Node, se inicia rápidamente y se integra limpiamente en un contenedor.
Lo mejor para: linting de especificaciones grandes rápidamente con conjuntos de reglas que ya tiene. Límite honesto: el ecosistema de conjuntos de reglas y la documentación aún se centran en Spectral, por lo que a menudo está escribiendo reglas contra el modelo de Spectral y ejecutándolas a través de vacuum. Eso es una característica, pero significa que Spectral sigue siendo lo primero que aprende.
Redocly CLI: lint más empaquetado en un solo binario
Redocly CLI tiene licencia MIT y cubre un trabajo ligeramente diferente. Realiza lint, pero su característica destacada es `bundle`: toma una especificación dividida en muchos archivos `$ref` (la forma sensata de mantener un diseño de API grande y mantenible) y la aplana en un solo documento para herramientas que esperan un solo archivo. También genera documentación de referencia de API a partir del resultado empaquetado.
npm install -g @redocly/cli
redocly lint openapi.yaml
redocly bundle openapi.yaml -o dist/openapi.yaml
Dividir su especificación en archivos por recurso mantiene los diffs legibles y los conflictos de fusión pequeños, lo cual es fundamental para un flujo de trabajo de diseño de API nativo de Git. El `bundle` de Redocly es el paso que convierte esa fuente multifile en el único artefacto que consume su CI, servidor simulado o sitio de documentos.
Lo mejor para: proyectos de especificación multifile que necesitan empaquetado más un pase de validación. Límite honesto: sus reglas de linting predeterminadas son más ligeras que un conjunto de reglas Spectral personalizado completo, por lo que muchos equipos ejecutan Redocly para el empaquetado y Spectral o vacuum para la aplicación profunda de estilos.
openapi-generator: convierte el diseño en clientes, stubs y documentación
El diseño no está terminado hasta que otras personas puedan construir sobre él. openapi-generator es Apache-2.0 y genera SDK de cliente, stubs de servidor y documentación a partir de una especificación OpenAPI en docenas de lenguajes. Tratar la especificación como la fuente de la verdad y generar el resto es el corazón de un enfoque schema-first, contract-driven, que cubrimos en los principios de diseño de API.
npm install -g @openapitools/openapi-generator-cli
openapi-generator-cli generate -i openapi.yaml -g typescript-axios -o ./client
Cambie `typescript-axios` por `go`, `python`, `java`, `kotlin` o cualquiera de los muchos generadores compatibles. Ejecútelo en CI en cada cambio de especificación y sus bibliotecas cliente nunca se desviarán del contrato.
Lo mejor para: mantener el código y la documentación generados sincronizados con el diseño. Límite honesto: necesita un JDK para ejecutarse (JDK 11+), el código generado es un punto de partida que a menudo personalizará, y la calidad del generador varía según el objetivo del lenguaje. Verifique la salida antes de enviarlo.
oasdiff: detecta cambios importantes antes de que lleguen a los clientes
Un linter le dice si una especificación está limpia. No puede decirle que cambiar el nombre de un campo acaba de romper todos los clientes en producción. oasdiff es la herramienta de Go con licencia Apache-2.0 que llena ese vacío: dele dos versiones de una especificación y le informará la diferencia, y específicamente los cambios importantes.
go install github.com/oasdiff/oasdiff@latest
oasdiff breaking old-openapi.yaml new-openapi.yaml
El comando `breaking` solo muestra los cambios que rompen a los consumidores existentes; `changelog` ofrece una lista legible por humanos de todo lo que cambió, sea o no un cambio importante; `diff` proporciona el delta completo legible por máquina. Conecte `oasdiff breaking` a una comprobación de solicitud de extracción y un cambio importante se convertirá en una compilación fallida en lugar de una llamada a las 3 a.m.
Lo mejor para: protegerse de cambios importantes en CI. Límite honesto: compara especificaciones, por lo que es tan bueno como su disciplina para mantener la especificación actualizada con la API real. No lint estilos; úselo junto con Spectral o vacuum.
Optic: diff y lint juntos, con una advertencia de mantenimiento
Optic tiene licencia MIT y hace algo que los otros dividen: lint y diff OpenAPI en una sola herramienta, comparando dos versiones para marcar cambios importantes mientras también aplica reglas de estilo. Incluso podría generar una especificación a partir del tráfico de prueba observado.
npm install -g @useoptic/optic
optic diff old-openapi.yaml new-openapi.yaml --check
Aquí está la honestidad que le debe una lista de código abierto: el repositorio público de Optic fue archivado a principios de 2026 y el proyecto ya no se mantiene activamente. El código fuente MIT todavía funciona, por lo que puede venderlo, pero no obtendrá nuevas reglas ni parches de seguridad. Para la detección de cambios importantes hoy, oasdiff es la opción mantenida; Optic permanece en la lista porque aún lo encontrará en pipelines existentes.
Lo mejor para: equipos que ya han invertido en él, o cualquiera que desee lint y diff en una sola CLI. Límite honesto: ya no se mantiene a partir de principios de 2026; trátelo como legado y planifique una ruta de migración.
Dónde encaja Apidog (y dónde no)
Apidog no es de código abierto, y no lint su OpenAPI ni aplica reglas de estilo; Spectral, vacuum y Redocly son sus linters, punto final. Lo que Apidog ofrece es una compensación diferente: en lugar de unir seis binarios separados, su nivel gratuito más el binario `apidog-cli` le brinda un lugar integrado para diseñar endpoints y esquemas de datos, luego exportar el resultado como OpenAPI para alimentar directamente estas comprobaciones de código abierto.
npm install -g apidog-cli
apidog login --with-token <YOUR_TOKEN>
apidog endpoint list
apidog export --format openapi -o openapi.yaml
La CLI tiene grupos de comandos para `endpoint`, `schema`, `mock` e `import`/`export`, de modo que puede scriptar el diseño de API desde el terminal y entregar la especificación exportada a openapi-generator o oasdiff. Consulte la guía completa de Apidog CLI para ver el conjunto completo de comandos. El encuadre honesto: Apidog es la opción comercial integrada que funciona bien con la cadena de herramientas de código abierto, no un reemplazo para un linter y no un proyecto de código abierto en sí mismo.
Cómo elegir
Haga coincidir la herramienta con la tarea. La mayoría de los equipos ejecutan dos o tres de estas juntas, no una.
| Herramienta | Mejor para | Instalación | ¿Código abierto? | Notas |
|---|---|---|---|---|
| Spectral | Linting de guía de estilo | npm i -g @stoplight/spectral-cli |
Sí (Apache-2.0) | El linter de referencia; escriba reglas personalizadas |
| vacuum | Linting rápido a escala | brew install --cask daveshanley/vacuum/vacuum |
Sí (MIT) | Ejecuta reglas de Spectral, rápido en Go |
| Redocly CLI | Empaquetado + validación | npm i -g @redocly/cli |
Sí (MIT) | Ideal para especificaciones `ref` de múltiples archivos |
| openapi-generator | Generación de SDK / stub / docs | npm i -g @openapitools/openapi-generator-cli |
Sí (Apache-2.0) | Necesita JDK 11+ |
| oasdiff | Detección de cambios importantes | go install github.com/oasdiff/oasdiff@latest |
Sí (Apache-2.0) | Mantenido; usar en revisiones de PR |
| Optic | Lint + diff en uno | npm i -g @useoptic/optic |
Sí (MIT) | Repo archivado a principios de 2026; legado |
| Apidog CLI | Diseño integrado + exportación | npm i -g apidog-cli |
No (nivel gratuito) | No es un linter; exporta OpenAPI |
Una pila práctica: Spectral o vacuum para estilo, Redocly para empaquetado, oasdiff para cambios importantes y openapi-generator para producir clientes. Si mantener tantas herramientas es más de lo que desea gestionar, una plataforma integrada cubre la parte de diseño y exportación en un solo lugar. Para una visión más amplia del panorama de herramientas más allá de la CLI, consulte nuestra guía sobre alternativas a Swagger para el diseño y las pruebas de API y los fundamentos en cómo diseñar APIs REST.
Conclusión
La cadena de herramientas CLI de código abierto para el diseño de API es madura y de uso gratuito: Spectral y vacuum lint, Redocly empaqueta, openapi-generator produce clientes y oasdiff protege contra cambios importantes, con Optic como una opción heredada a reconocer. Conéctelos a su CI y su contrato de API se verificará en cada push sin costo por asiento y sin dependencia del proveedor.
Si prefiere diseñar endpoints y esquemas en una herramienta integrada y exportar OpenAPI limpio a esa misma pipeline, Descargue Apidog y pruebe `apidog-cli`; es el compañero comercial de la pila de código abierto, no un reemplazo para su linter. De cualquier manera, el objetivo es el mismo: detectar problemas de diseño en el terminal, antes de que lleguen a sus usuarios.