Hay dos formas habituales de trabajar con OpenAPI en un equipo: escribir la especificación a mano en Git o diseñarla visualmente y exportarla cuando el CI lo exige.
La primera opción suele ser más lenta al inicio, pero más estable a largo plazo. La segunda acelera la incorporación, pero puede generar desviaciones entre “lo que está en la herramienta” y “lo que vive en el repositorio”.
Durante mucho tiempo, Apidog encajaba mejor en el segundo flujo: diseñador visual, generación de OpenAPI y exportaciones cuando hacía falta. Con el Modo Spec-First (Beta), Apidog añade un flujo distinto: editar directamente archivos OpenAPI .yaml o .json sincronizados con Git.
Probé la beta con una especificación OpenAPI real de un proyecto paralelo. Esto es lo que conviene saber antes de usarla en un equipo.
Lo que cambia con el Modo Spec-First
Apidog ahora tiene dos modos de proyecto con modelos de trabajo distintos.
En el modo predeterminado, creas endpoints desde formularios visuales. Apidog genera la especificación OpenAPI a partir de esos datos. Es útil si el equipo no escribe YAML con frecuencia.
En el Modo Spec-First, el archivo OpenAPI es la fuente de verdad:
- Editas archivos
.yamlo.jsondirectamente. - El proyecto se sincroniza con un repositorio Git.
- El editor incluye resaltado de sintaxis.
- El autocompletado entiende el esquema OpenAPI.
- La barra lateral genera un esquema navegable de rutas en tiempo real.
La diferencia práctica es importante: no estás editando una representación visual que luego se serializa. Estás editando el archivo que vive en Git.
La parte más útil es la vista de esquema. YAML no es difícil, pero sí puede ocultar la estructura cuando el archivo crece. Aquí puedes escribir la especificación y, al mismo tiempo, navegar por rutas, métodos y endpoints desde la barra lateral.
Configuración paso a paso
Este fue el flujo que seguí. Me tomó menos de diez minutos, incluyendo la autorización de Git.
1. Crea un proyecto en Modo Spec-First
Desde la pantalla de proyectos:
+ Nuevo Proyecto → General → Modo Spec-first
El selector puede pasar desapercibido porque el Modo General aparece como recomendado. Si quieres trabajar con archivos OpenAPI desde Git, asegúrate de elegir Modo Spec-first al crear el proyecto.
2. Conecta el repositorio Git
En el mismo diálogo, ve a Conectar con Repositorio Git y autoriza tu proveedor.
Después selecciona:
- Organización
- Repositorio
- Rama principal
Apidog usará esa rama como origen para sincronizar los archivos de especificación.
3. Configura el proyecto
Completa:
- Nombre del Proyecto
- Permisos del equipo
- Configuración de acceso
Luego haz clic en Crear.
En la primera sincronización, Apidog importa los archivos .yaml y .json del repositorio al workspace.
4. Edita la especificación como código
Abre un archivo YAML.
El editor se comporta como un editor de código real:
paths:
/store/token:
post:
summary: Create store token
responses:
"200":
description: Token created
Mientras escribes, Apidog actualiza la barra lateral con las rutas detectadas. Puedes hacer clic en un endpoint y saltar directamente a la línea correspondiente.
Si ya usas VS Code con extensiones para OpenAPI, el flujo se siente familiar, pero con navegación integrada dentro de Apidog.
5. Haz commit y push
Cuando termines de editar, usa el botón:
Commit & Push
El diálogo muestra:
- Archivos modificados
- Campo de mensaje de commit
- Botón Push
- Opción para descartar todos los cambios
No hay un paso separado de staging. Todo lo que aparece en Cambios entra en el commit, salvo que lo desmarques.
6. Revisa el estado de sincronización
En la esquina inferior izquierda aparece el estado de sincronización, por ejemplo:
Sincronizado ahora mismo
Ese indicador te dice si:
- Tus cambios ya están enviados.
- El remoto tiene cambios nuevos.
- Tu copia está desincronizada.
En la práctica, es el elemento que más conviene vigilar. Si está en verde, el editor y el repositorio están alineados.
Lo que noté al usarlo
Hay tres detalles importantes para equipos que ya trabajan con OpenAPI en Git.
La vista de esquema se actualiza rápido
En otros editores OpenAPI, la estructura suele actualizarse al guardar o después de un retardo. En esta beta, la barra lateral se actualizaba mientras escribía.
Eso cambia el uso de la herramienta: la vista de esquema deja de ser un reporte y se convierte en navegación real.
La sincronización con Git es bidireccional
Probé editar el mismo archivo desde mi clon local y hacer push desde la terminal mientras Apidog seguía abierto.
El resultado:
- Apidog detectó que el remoto tenía cambios.
- El indicador cambió a estado atrasado.
- Pude traer los cambios al editor con un clic.
Esto permite que distintos perfiles trabajen con el mismo archivo:
- Quien prefiere Vim o VS Code puede seguir usando su editor.
- Quien prefiere Apidog puede editar desde la UI.
- Git sigue siendo la fuente de verdad.
No puedes volver al diseñador visual dentro del mismo proyecto
Esto es clave antes de adoptar el modo.
Si creas un proyecto como Spec-First, ese proyecto queda en ese modelo. No puedes cambiarlo después al diseñador visual porque los modelos de datos internos son distintos.
Si tu equipo necesita ambos flujos, una opción práctica es:
- Mantener la especificación en un repositorio Git.
- Crear un proyecto Spec-First apuntando a ese repositorio.
- Crear otro proyecto visual que importe desde la misma fuente cuando sea necesario.
No es un flujo perfecto, pero mantiene una única especificación como referencia.
Cuándo usarlo
El Modo Spec-First encaja bien si tu equipo ya trata OpenAPI como un artefacto versionado.
Úsalo si:
- Escribes OpenAPI a mano.
- Ejecutas validaciones como
spectral linten CI. - Generas SDKs o clientes desde la especificación.
- Quieres revisar cambios de API mediante pull requests.
- Ya tienes archivos
.yamlo.jsonen Git. - Quieres evitar diferencias entre “la especificación en la herramienta” y “la especificación en el repositorio”.
También es útil si hoy tienes un paso tipo:
make export
y nadie confía del todo en que el resultado refleje el estado real de la API.
Cuándo no usarlo
No lo usaría como primera opción si el equipo nunca ha trabajado con OpenAPI.
Si tus colaboradores dependen del diseñador visual para crear endpoints, schemas y respuestas, el modo predeterminado sigue siendo más adecuado. El Modo Spec-First prioriza fidelidad y control sobre facilidad de incorporación.
Tampoco es ideal, por ahora, si necesitas mezclar edición visual y edición spec-first dentro del mismo proyecto. La beta todavía separa claramente ambos modos.
Conclusión
El desarrollo spec-first no debería obligarte a elegir entre Git y una plataforma de diseño de APIs.
Con este modo, Apidog cambia el punto de control: el archivo del repositorio es el archivo que editas. La UI sirve para navegar, autocompletar, validar visualmente y sincronizar, pero no reemplaza al artefacto principal.
Si tu equipo ya trabaja con OpenAPI en Git, el flujo recomendado es simple:
- Crea un proyecto en Modo Spec-First.
- Conéctalo a un repositorio existente.
- Edita un archivo
.yamlo.json. - Revisa el esquema generado en la barra lateral.
- Haz Commit & Push.
- Verifica el estado de sincronización.
La beta está disponible desde el diálogo de Nuevo Proyecto. El primer commit puede tomar unos minutos. La decisión real es si el flujo sigue funcionando después de una semana de trabajo con tu equipo.
Top comments (0)