Hay dos bandos en cada equipo de API con el que he trabajado.
Uno escribe su especificación OpenAPI a mano, la guarda en un directorio `specs/` y trata a Git como la fuente de verdad. El otro hace clic a través de un diseñador visual, exporta la especificación cuando el CI se queja y parchea cualquier desviación que las dos representaciones hayan acumulado desde el martes pasado.
He vivido en ambos bandos. El primero es más lento el primer día y más rápido el día noventa. El segundo es lo opuesto. Y hasta hace aproximadamente un mes, la herramienta de diseño de API que más uso — Apidog — solo se ajustaba realmente al segundo bando. Su diseñador visual es excelente. Su viaje de ida y vuelta de YAML era una característica que tenías que defender en la revisión de código.
Luego, a mediados de abril, el Modo Spec-First (Beta) apareció en el diálogo de Nuevo Proyecto. Deliberadamente no escribí sobre ello el día del lanzamiento. Quería usarlo en algo real primero, y quería esperar lo suficiente para que los errores de las primeras semanas tuvieran la oportunidad de aparecer. Un mes es aproximadamente la cantidad de tiempo correcta. Esta publicación es lo que encontré después de pasar una mañana con la beta frente a una especificación OpenAPI de uno de mis proyectos paralelos — lo que le diría a un compañero de equipo antes de que lo probara, y dónde encaja y dónde no.
Lo que realmente cambia el Modo Spec-First
La versión corta: Apidog ahora tiene dos modos de proyecto, y son productos genuinamente diferentes en su base.
El modo predeterminado es lo que la mayoría de la gente conoce. Haces clic en + Nuevo Proyecto, obtienes un árbol de carpetas y formularios visuales, y construyes puntos finales rellenando campos. La especificación OpenAPI se genera automáticamente. Funciona, especialmente para equipos que no tienen ya un fuerte hábito con YAML.
El Modo Spec-First reemplaza el editor de formularios con un editor de código real sobre archivos `.yaml` y `.json` sin procesar, además de una sincronización bidireccional con tu repositorio Git. Tu especificación OpenAPI es el archivo en disco, no una serialización de clics. Hay resaltado de sintaxis, autocompletado según el esquema OpenAPI y un panel de 'Análisis de Directorio en Tiempo Real' que construye un esquema de puntos finales en la barra lateral a partir de tu código mientras escribes.
Ese último detalle es con el que comenzaría si estuviera demostrando esto a un escéptico. La razón por la que existen los diseñadores visuales no es porque YAML sea difícil, es porque YAML oculta la estructura hasta que ya te has desplazado más allá de ella. La vista de esquema de Apidog resuelve eso sin obligarte a abandonar el archivo. Escribes la especificación, obtienes navegación. Los dos coexisten en la pantalla.
La tesis, si es que hay alguna: el desarrollo ‘spec-first’ nunca se trató de preferir los editores de texto. Se trataba de quién posee el artefacto. El Modo Spec-First convierte el artefacto en el archivo de tu repositorio, punto. La interfaz de usuario es una ventana a él, no un envoltorio alrededor de él.
La configuración, de principio a fin
Aquí está el camino que seguí. Me tomó menos de diez minutos, la mayor parte de los cuales fue la autorización de Git.
1. Crea el proyecto en el modo correcto. Desde la pantalla de proyectos, **+ Nuevo Proyecto → General → Modo Spec-first**. El selector de modo es fácil de pasar por alto si has estado creando proyectos en piloto automático durante un año — el Modo General está marcado como 'Recomendado' y tu vista se desliza directamente más allá del segundo mosaico. Tómate tu tiempo aquí.
2. Conéctate a tu repositorio Git. Desplázate hasta **Conectar con Repositorio Git** y autoriza a tu proveedor. Yo usé GitHub; la documentación cubre los demás. Luego elige la **Organización**, el **Repositorio** y la **Rama principal**. Apidog sincronizará los archivos de especificación en esa rama como tu copia de trabajo.
3. Configura el proyecto. Introduce un **Nombre de Proyecto**, establece los permisos del equipo y haz clic en **Crear**. La primera sincronización trae todos los archivos `.yaml` y `.json` que se encuentren en el repositorio al espacio de trabajo de Apidog.
4. Edita la especificación como un archivo, no como un formulario. Abre uno de los archivos YAML. Obtendrás un editor real, autocompletado consciente del esquema y el esquema del punto final materializándose en la barra lateral mientras escribes. Si has pasado algún tiempo en VS Code con la extensión OpenAPI, esto te resultará familiar — excepto que el esquema está conectado a la navegación, y al hacer clic en un punto final, saltarás a la línea correcta.
5. Confirma y envía. Arriba a la derecha, **Commit & Push**. El diálogo se abre a una sección de **Cambios** que lista los archivos modificados, un campo de **Mensaje de Commit** y dos botones: **Push** o **Descartar todos los cambios**. No hay un paso de preparación separado — todo lo que esté en Cambios irá al commit. Esa es una simplificación deliberada, y para la mayoría de los flujos de trabajo de edición de especificaciones, es la decisión correcta.
6. Observa el indicador de sincronización. Esquina inferior izquierda — puedes verlo como **Sincronizado ahora mismo** en la Figura 1. Te indica si tus ediciones locales han sido enviadas, recibidas o están desincronizadas con el remoto. Lo dejé abierto en una esquina de mi pantalla y se convirtió en lo que más confiaba que los diálogos modales. Si el indicador está en verde, tú y el repositorio están de acuerdo.
Esa es toda la superficie de trabajo. Seis pasos, sin motor de sincronización separado para configurar, sin plugins para instalar.
Lo que noté y que la documentación no te dice
Tres cosas que vale la pena señalar, todas de una mañana de experimentación.
La vista de esquema se actualiza más rápido de lo que esperaba. He utilizado varios 'editores OpenAPI en vivo' en el pasado y la mayoría de ellos vuelven a analizar al guardar, lo que significa un retraso de 30 segundos entre añadir un punto final y verlo en la barra lateral. El esquema de Apidog se actualizaba mientras escribía — lo suficientemente instantáneo como para que dejara de comprobarlo. Eso suena a algo pequeño. No lo es. Es la diferencia entre confiar en el esquema como ayuda a la navegación y comprobarlo como un informe de estado.
La integración con Git es genuinamente bidireccional. Edité el mismo archivo en mi clon local y lo subí desde la terminal mientras Apidog estaba abierto. Apidog lo notó, el indicador de sincronización cambió a 'atrasado', y con un solo clic se incorporaron los cambios al editor sin diálogo de fusión. La sincronización bidireccional que la documentación promete es la experiencia real, no un resumen de marketing. Si tienes un compañero de equipo que se niega a usar otra cosa que no sea Vim, él puede seguir usando Vim, tú puedes seguir usando Apidog, y el archivo en el repositorio sigue siendo lo único que ambos están editando.
No hay un 'botón de escape' para volver al diseñador visual en el mismo proyecto. Esto es intencional, pero vale la pena saberlo antes de comprometerte. Si eliges el Modo Spec-First al crear, ese proyecto es 'spec-first'. No puedes cambiar un proyecto a mitad de camino porque los modelos de datos subyacentes son diferentes. Para un equipo que quiere ambos modos en la misma especificación, el flujo de trabajo es: mantener la especificación en un repositorio, apuntar un proyecto Spec-First hacia ella, y permitir que los usuarios del modo visual abran un proyecto separado que importe de la misma fuente. No es perfecto, pero es funcional.
Dónde encaja y dónde no
Voy a usar esto en producción. Esa es la respuesta más directa que puedo dar. La combinación de un editor real, autocompletado que respeta el esquema OpenAPI y un indicador de sincronización en el que puedo confiar es lo que he deseado de Apidog durante dos años.
Pero aquí está la versión honesta de para quién es esto.
Encaja si ya escribes OpenAPI a mano, o quieres hacerlo. Encaja si tu CI ejecuta `spectral lint` o genera SDK de cliente a partir de la especificación y la especificación necesita vivir en Git de todos modos. Encaja si tienes un ingeniero en el equipo que, de otro modo, estaría abriendo solicitudes de extracción contra el archivo YAML desde VS Code, y quieres que todos converjan en una sola herramienta sin obligarlos a dejar su teclado. Y encaja especialmente bien si has estado gestionando la desviación entre 'la especificación en Apidog' y 'la especificación en el repositorio' con un paso de `make export` en el que nadie confía.
No encaja si tu equipo nunca ha tocado OpenAPI y el diseñador visual es la razón por la que pueden contribuir. Para esos equipos, el modo predeterminado sigue siendo la opción correcta. El Modo Spec-First sacrifica la facilidad de incorporación por la fidelidad, y ese intercambio es incorrecto cuando la mayoría de tus colaboradores no son especialistas en API.
Tampoco encaja, todavía, para equipos que necesitan combinar ambos modos en el mismo proyecto. La beta es genuinamente una beta en ese aspecto. Esperaría que esto se flexibilizara en las próximas versiones.
La conclusión
El desarrollo ‘spec-first’ solía significar optar por no usar herramientas de diseño de API. O vivías en YAML y renunciabas a los ejecutores de pruebas y servidores de prueba, o vivías en un diseñador visual y renunciabas a Git como la fuente de verdad. El movimiento interesante en el Modo Spec-First es que Apidog ha dejado de pedirte que elijas.
El archivo en tu repositorio es el archivo en el editor. El esquema es una vista, no un estado. La sincronización de Git es el cable, no una característica. Si has estado esperando una plataforma de API que se tome en serio el enfoque 'spec-first' en lugar de tratarlo como una opción de exportación, esta es la que yo probaría.
La beta está disponible en el diálogo de Nuevo Proyecto hoy. Descarga Apidog, elige el Modo Spec-First al crear y apúntalo a un repositorio en el que ya confíes. El primer commit tarda diez minutos. La decisión de si mantenerlo o no toma aproximadamente una semana.