La mayoría de los tutoriales de diseño de API comienzan con un ratón. Abres un editor visual, arrastras un esquema a un lienzo, haces clic en diálogos para añadir un campo. Eso funciona, pero no encaja con la forma en que muchos equipos realmente despliegan. Si la definición de tu API reside en Git, se revisa en pull requests y pasa por CI, quieres diseñarla de la misma manera que la despliegas: desde la terminal, en texto, con comandos que puedes automatizar.
Diseñar APIs desde la línea de comandos significa que tú eres el autor del contrato, lo validas según una guía de estilo, lo empaquetas en un solo archivo y generas stubs, todo sin salir de la shell. Cada paso es repetible. Cada paso puede ejecutarse en un pipeline. Y cuando un agente de IA o un compañero de equipo necesita reproducir tu configuración, ejecutan los mismos comandos que tú en lugar de adivinar qué botones hiciste clic.
Esta guía recorre dos caminos. Primero, la ruta general de código abierto construida a partir de herramientas de propósito único: crear un archivo OpenAPI, validarlo con Spectral, empaquetarlo con la CLI de Redocly y generar stubs de servidor con openapi-generator. Luego, la ruta de la CLI de Apidog, donde el diseño, los esquemas, los endpoints y la autenticación viven en un solo proyecto que puedes manejar desde la terminal. Si primero quieres el trasfondo conceptual más profundo, lee nuestra guía sobre cómo diseñar una API y el tutorial sobre diseñar APIs REST.
Si estás siguiendo con Apidog, primero descarga el binario. Nuestra guía de instalación de la CLI de Apidog cubre el paso npm install -g apidog-cli y el handshake apidog login --with-token, y la guía completa de la CLI de Apidog mapea cada grupo de comandos.
La ruta general de código abierto: crear, validar, empaquetar, generar
El stack clásico de diseño CLI es un conjunto de herramientas independientes que conectas entre sí. Mantienes la definición de tu API en un archivo OpenAPI bajo control de versiones y ejecutas cada herramienta como un paso. Este es el flujo de trabajo de diseño de API nativo de Git, y es realmente bueno. Así es como se ve.
Crear el documento OpenAPI
Comienzas con un archivo YAML simple. No se requiere un editor especial; cualquier editor de texto funciona. Un openapi.yaml mínimo se ve así:
openapi: 3.0.3
info:
title: Orders API
version: 1.0.0
paths:
/orders/{orderId}:
get:
operationId: getOrder
parameters:
- name: orderId
in: path
required: true
schema:
type: string
responses:
'200':
description: An order
content:
application/json:
schema:
$ref: '#/components/schemas/Order'
components:
schemas:
Order:
type: object
required: [id, status]
properties:
id:
type: string
status:
type: string
enum: [pending, shipped, delivered]
A medida que la API crece, la divides en varios archivos y los referencias con $ref. Esto mantiene cada esquema legible y revisable por sí mismo.
Validar con Spectral
El OpenAPI escrito a mano tiende a desviarse. Alguien olvida un operationId, otra persona deja una respuesta indocumentada, una tercera inventa su propia convención de nombres. Un linter detecta todo eso antes de la revisión. Spectral, de Stoplight, es la elección estándar. Viene con conjuntos de reglas para OpenAPI y te permite escribir los tuyos propios.
npm install -g @stoplight/spectral-cli
spectral lint openapi.yaml
Spectral imprime cada violación con un número de línea y gravedad. Puedes hacer que la construcción falle en caso de errores verificando el código de salida en CI. La CLI de Redocly y vacuum hacen el mismo trabajo si quieres una alternativa; vacuum es rápido y se instala como un linter compatible con Spectral. El punto se mantiene independientemente de cuál elijas: la validación es una herramienta separada y dedicada, y la ejecutas como su propio paso.
Empaquetar con la CLI de Redocly
Una vez que tu definición está dividida en varios archivos, la mayoría de las herramientas posteriores quieren un único documento autocontenido. La CLI de Redocly resuelve cada $ref y aplana el árbol en un solo archivo.
npm install -g @redocly/cli
redocly bundle openapi.yaml -o dist/openapi.bundled.yaml
Redocly también valida (redocly lint) y previsualiza la documentación, por lo que algunos equipos la utilizan tanto para la verificación de estilo como para el empaquetado. Sus documentos oficiales listan el conjunto completo de comandos.
Generar stubs con openapi-generator
Con una especificación limpia y empaquetada, generas código. openapi-generator convierte un documento OpenAPI en stubs de servidor, SDKs de cliente y más en docenas de lenguajes.
npm install -g @openapitools/openapi-generator-cli
openapi-generator-cli generate \
-i dist/openapi.bundled.yaml \
-g spring \
-o ./server
Cambia -g spring por -g python-flask, -g go-server o cualquiera de los generadores compatibles. Ahora tienes un andamiaje que coincide exactamente con tu contrato.
Esa es la ruta abierta de principio a fin: cuatro herramientas, cuatro comandos, todos automatizables. El costo es el cableado. Tú mismo mantienes la estructura de archivos, la configuración del linter, el paso de empaquetado y la configuración del generador, y cada herramienta tiene sus propias convenciones. Funciona bien cuando quieres el máximo control y no te importa el pegamento.
La ruta de la CLI de Apidog: diseño en un solo proyecto
El otro enfoque mantiene el diseño, los esquemas, los endpoints, los mocks y la autenticación dentro de un único proyecto que manejas desde la terminal. El binario apidog-cli es una CLI completa de recursos de proyecto, no solo un ejecutor de pruebas. Tiene grupos de comandos para toda la superficie de diseño: schema para modelos de datos, endpoint para operaciones, folder para organización, security-scheme para autenticación, además de import, export, mock y más.
Una nota honesta de antemano: Apidog no valida tu OpenAPI ni aplica una guía de estilo. No es para eso. Si necesitas validación, mantén Spectral o vacuum en tu pipeline. Apidog tampoco es de código abierto; es un producto comercial con una versión gratuita. Lo que te ofrece es un proyecto integrado para que no tengas que unir las piezas de diseño tú mismo. Nuestra opinión sobre las alternativas a Swagger para el diseño y las pruebas de API cubre dónde tiene sentido ese compromiso.
Instala y autentica primero (consulta la guía de instalación para la configuración del token):
npm install -g apidog-cli
apidog login --with-token <TU_ACCESS_TOKEN>
Cada comando devuelve JSON estructurado, y la mayoría de las respuestas incluyen un bloque agentHints.nextSteps que te indica (o a un agente) qué ejecutar a continuación. Añade --help a cualquier comando para ver sus flags exactos.
Definir modelos de datos con apidog schema
El diseño comienza con tus datos. Un esquema Order reutilizable se convierte en la única fuente de verdad a la que hacen referencia los endpoints, la misma idea que components/schemas en OpenAPI puro, pero gestionado como un recurso del proyecto.
apidog schema --help
apidog schema create --project <ID_DEL_PROYECTO>
Debido a que la salida es JSON, puedes canalizarla a través de jq para obtener el ID del nuevo esquema e introducirlo en el siguiente comando. Si ya tienes un archivo OpenAPI, impórtalo en lugar de volver a escribir todo:
apidog import --project <ID_DEL_PROYECTO> --file openapi.yaml
apidog import acepta formatos OpenAPI 3.x, Swagger 2.0, Postman y Apidog, por lo que una definición existente se convierte en un proyecto activo en un solo paso.
Definir endpoints con apidog endpoint
Con los modelos en su lugar, añades operaciones. El grupo endpoint crea y actualiza endpoints, conectándolos a los esquemas que definiste y a las carpetas que los organizan.
apidog endpoint --help
apidog endpoint list --project <ID_DEL_PROYECTO>
apidog endpoint create --project <ID_DEL_PROYECTO>
Listar los endpoints como JSON es útil por sí mismo. Puedes comparar la salida entre ramas o alimentarla a un script que verifique que cada ruta tenga las respuestas que esperas. Agrupa los endpoints relacionados con el comando folder para que el proyecto siga siendo navegable a medida que crece.
Definir autenticación con apidog security-scheme
La autenticación es parte del contrato, no una ocurrencia tardía. El grupo security-scheme define cómo se autentican los clientes: claves API, tokens portadores, OAuth 2.0, etc. Esto se mapea a components/securitySchemes en OpenAPI, por lo que la importación y exportación se realizan de forma limpia.
apidog security-scheme --help
apidog security-scheme list --project <ID_DEL_PROYECTO>
Definir el esquema una vez a nivel de proyecto significa que cada endpoint puede hacer referencia a él en lugar de que cada operación redeclare su propia autenticación. Esa es exactamente la clase de consistencia por la que un linter te regañaría de otra manera.
Validar tus escrituras con apidog cli-schema validate
Antes de que hagas commit de cambios o entregues un proyecto a CI, quieres saber que tus definiciones de recursos están bien formadas. La CLI incluye un comando cli-schema validate que verifica un archivo de definición contra el esquema que espera la CLI, de modo que una escritura mal formada falla rápidamente en lugar de pasar silenciosamente.
apidog cli-schema --help
apidog cli-schema validate --file resource.json
Ejecuta esto como un paso de guardia en tu pipeline: valida primero, luego aplica. Un código de salida distinto de cero detiene el pipeline antes de que un recurso incorrecto llegue al proyecto. Esto es la validación de tus escrituras de la CLI, no la validación de estilo OpenAPI; esos son dos trabajos diferentes, y todavía querrás Spectral para el segundo.
Exportar de vuelta a OpenAPI
Diseña en Apidog, luego entrega un artefacto estándar al resto de tu cadena de herramientas. apidog export escribe en OpenAPI, HTML, Markdown o Postman.
apidog export --project <ID_DEL_PROYECTO> --format openapi -o dist/openapi.yaml
Ahora vuelves a un archivo OpenAPI portátil. Aliméntalo a Spectral para su validación, a openapi-generator para los stubs, o a la construcción de tu documentación. El proyecto integrado y el stack de herramientas abiertas no son mutuamente excluyentes; la exportación es el puente entre ellos.
Conectarlo a CI
Ambas rutas brillan en un pipeline porque cada comando tiene un código de salida y una salida de texto. Un trabajo mínimo de verificación de diseño podría ejecutar el linter, luego validar, y luego empaquetar:
# falla en violaciones de estilo
spectral lint openapi.yaml
# valida cualquier escritura de recursos de la CLI antes de aplicar
apidog cli-schema validate --file resource.json
# aplanar a un solo artefacto para los pasos posteriores
redocly bundle openapi.yaml -o dist/openapi.bundled.yaml
Dado que la salida de Apidog es JSON con agentHints.nextSteps, este flujo también es manejado limpiamente por un agente de codificación de IA. El agente lee el resultado estructurado, ve el siguiente paso sugerido y lo ejecuta, sin necesidad de hacer screen-scraping de una GUI. Esa es la razón principal para diseñar desde la CLI en primer lugar: lo que un humano escribe, un script o un agente también puede escribirlo.
Inconvenientes comunes
Los archivos divididos rompen las herramientas posteriores. Una definición distribuida en muchos archivos $ref es excelente para los humanos y engorrosa para los generadores. Siempre empaqueta en un solo archivo antes de generar código o publicar documentos. redocly bundle es la solución.
Esperas que Apidog valide. No lo hará. Apidog gestiona recursos; no aplica una guía de estilo ni señala violaciones de reglas de OpenAPI. Mantén Spectral o vacuum en el ciclo para eso. Confundir apidog cli-schema validate con un linter es el error común; valida la estructura del recurso, no el estilo de OpenAPI.
Olvidarse de importar antes de editar. Si estás editando una API existente a través de la CLI, primero importa la definición de origen al proyecto. Editar un proyecto vacío y esperar que tus antiguos endpoints estén allí es una forma rápida de confundirse.
Autenticación definida por endpoint en lugar de una sola vez. Define un security-scheme a nivel de proyecto y haz referencia a él. Redefinir la autenticación en cada operación es cómo los contratos se desvían.
Conclusión
Diseñar APIs desde la CLI convierte una tarea que requiere muchos clics en un conjunto de comandos repetibles. La ruta abierta, crear, validar con Spectral, empaquetar con Redocly, generar con openapi-generator, te da control total y sin ataduras. La ruta de la CLI de Apidog te ofrece un proyecto integrado donde los esquemas, endpoints y autenticación conviven y cada comando devuelve JSON listo para agentes. La exportación es el puente entre ambos, para que nunca te quedes atascado.
Elige la ruta que mejor se adapte a tu equipo. Si ya vives en Git con un montón de herramientas de propósito único, mantenlas y añade apidog export cuando quieras un artefacto portátil. Si prefieres no mantener el pegamento, descarga Apidog, instala la CLI y diseña tu próxima API sin tocar un ratón.