¿Qué es el Modo Spec-First de Apidog?

El Modo Apidog Spec-First es un espacio de trabajo beta para equipos que tratan su especificación OpenAPI como código fuente. En lugar de editar formularios, trabaja directamente sobre openapi.yaml u openapi.json en un editor estilo IDE y sincroniza los cambios en ambos sentidos con un repositorio Git conectado.

Prueba Apidog hoy

Esta guía explica cómo usar el modo Spec-First en la práctica: qué resuelve, cómo configurarlo, cómo trabajar con Git, qué limitaciones tiene la beta y cuándo conviene usarlo. Para el contexto del enfoque, consulte el artículo sobre el flujo de trabajo de API git-native.

¿Qué es el Modo Apidog Spec-First?

El Modo Spec-First es un modo de edición beta en Apidog donde el diseño de la API vive como un documento OpenAPI sin procesar.

El flujo básico es:

1. Abrir la especificación OpenAPI.
2. Editar YAML o JSON directamente.
3. Validar la estructura mientras escribe.
4. Confirmar los cambios con un mensaje de commit.
5. Enviar los cambios al repositorio Git conectado.
6. Extraer cambios de otros miembros del equipo cuando sea necesario.

Este modo está pensado para equipos que ya trabajan con Git como fuente de verdad: backend, plataforma, equipos API-first y organizaciones que revisan contratos de API mediante pull requests.

La diferencia principal frente a muchas herramientas de API es simple: Apidog no oculta la especificación detrás de formularios. En Spec-First, el archivo es el proyecto.

Modo Spec-First vs Modo Design-First

Apidog ofrece dos formas de diseñar APIs:

• Modo Design-First: editor visual basado en formularios.
• Modo Spec-First: editor de código para trabajar directamente con OpenAPI.

Para una comparación más completa, consulte la comparación entre spec-first y design-first.

Aspecto	Modo Design-First	Modo Spec-First (Beta)
Editor principal	Formularios visuales y paneles UI	Editor YAML/JSON
Fuente de verdad	Base de datos del proyecto Apidog	Archivo de especificación en Git
Sincronización Git	Exportación/importación	Sincronización bidireccional
Mejor para	Equipos mixtos, diseño visual	Equipos Git-native
Curva de aprendizaje	Guiada	Familiar si conoce OpenAPI

Ningún modo es universalmente mejor. Use Spec-First si su equipo quiere revisar y versionar la especificación como código. Use Design-First si necesita una experiencia más visual y guiada.

Características clave

Editor OpenAPI estilo IDE

El centro del modo Spec-First es un editor de código para documentos OpenAPI en YAML o JSON.

El editor incluye:

• Resaltado de sintaxis.
• Validación contra la especificación OpenAPI.
• Autocompletado para OpenAPI y Swagger.
• Edición directa del archivo de especificación.

Ejemplo de operación OpenAPI:

paths:
  /users/{userId}:
    get:
      summary: Get a user by ID
      operationId: getUserById
      parameters:
        - name: userId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: A single user
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'

Esto es útil cuando trabaja con estructuras grandes y necesita ayuda contextual para evitar errores como campos mal escritos, referencias inválidas o propiedades fuera de lugar.

Esquema navegable auto-parseado

Los archivos OpenAPI crecen rápido. Una API real puede tener miles de líneas.

Spec-First analiza automáticamente el documento y genera una navegación lateral con:

• Rutas.
• Operaciones.
• Esquemas.
• Componentes.

Puede hacer clic en una operación como POST /orders y saltar directamente a esa sección del archivo. El esquema se actualiza a medida que modifica la especificación, por lo que refleja el estado real del documento.

En la práctica, esto evita depender del desplazamiento manual o de búsquedas repetidas dentro de openapi.yaml.

Sincronización Git bidireccional

La sincronización con Git es el núcleo del modo Spec-First.

Apidog puede traer cambios desde el repositorio y enviar sus ediciones de vuelta. Esto permite que la especificación OpenAPI siga el mismo flujo que el resto del código.

Proveedores compatibles:

Proveedor	Cómo se conecta
GitHub	Integración directa
GitLab	Integración directa
Azure DevOps	Conexión Git genérica

Para un flujo específico con GitHub, consulte la guía para sincronizar una especificación OpenAPI con GitHub.

Commit, push e indicador de sincronización

El modo Spec-First sigue un flujo Git familiar:

1. Edita la especificación.
2. Revisa los cambios detectados.
3. Escribe un mensaje de commit.
4. Confirma los cambios.
5. Hace push al repositorio conectado.

El indicador de sincronización muestra el estado actual, por ejemplo:

• Si la especificación local está sincronizada con el repositorio.
• Si existen cambios sin enviar.
• Si debe extraer cambios recientes.

Esto reduce el riesgo de trabajar sobre una versión obsoleta del contrato API.

Seguimiento de cambios en archivos

Antes de hacer commit, Apidog muestra qué archivos cambiaron y cómo cambiaron:

• Modificados.
• Añadidos.
• Eliminados.

Este paso funciona como un punto de control antes de publicar cambios en Git. Si una edición fue experimental o incorrecta, puede descartarla antes de enviarla al repositorio.

Proyectos vinculados a repositorio y rama

Un proyecto Spec-First se crea desde un repositorio y una rama específicos, por ejemplo main.

Eso significa que el proyecto siempre apunta a una ubicación concreta en Git:

• Un repositorio.
• Una rama.
• Un archivo de especificación.
• Un historial compartido.

Durante la configuración también puede definir permisos de equipo para controlar quién accede al proyecto y qué acciones puede realizar.

Cómo configurar el Modo Spec-First

La configuración es lineal. También puede consultar el tutorial oficial en la documentación de Spec-First Mode.

1. Cambie al Modo Spec-First

Abra el módulo de APIs en Apidog.

En la parte inferior izquierda, cambie de Modo Design-First a Modo Spec-First.

2. Conecte su proveedor Git

Seleccione el proveedor que utiliza su equipo:

• GitHub.
• GitLab.
• Azure DevOps mediante conexión Git genérica.

Para Azure DevOps, configure la conexión con credenciales Git estándar.

3. Cree el proyecto desde un repositorio

Seleccione:

• Repositorio.
• Rama, normalmente main.
• Archivo OpenAPI que desea editar.

Apidog crea el proyecto con ese repositorio y rama como ámbito.

4. Configure permisos de equipo

Defina quién puede acceder al proyecto y qué puede modificar.

Esto permite alinear el acceso de Apidog con el modelo de permisos que ya usa en Git.

5. Edite openapi.yaml u openapi.json

Abra la especificación en el editor.

Use:

• Autocompletado para escribir estructuras válidas.
• Validación para detectar errores.
• Navegación lateral para saltar entre rutas y componentes.

6. Revise los cambios

Antes del commit, inspeccione los archivos modificados.

Verifique que solo está confirmando lo que realmente quiere publicar.

7. Haga commit

Escriba un mensaje claro, por ejemplo:

Add POST /invoices endpoint

Luego confirme los cambios.

8. Haga push al repositorio

Envíe el commit a la rama conectada.

9. Verifique la sincronización

Revise el indicador de estado.

Cuando la especificación local y el repositorio coincidan, el proyecto estará sincronizado.

Flujo de trabajo diario recomendado

Un flujo práctico con Spec-First puede verse así:

1. Hacer pull al iniciar el día.
2. Abrir la operación o esquema que va a modificar.
3. Editar el YAML o JSON.
4. Validar errores en tiempo real.
5. Revisar los cambios detectados.
6. Hacer commit con un mensaje claro.
7. Hacer push.
8. Abrir o actualizar la pull request correspondiente en Git.

Ejemplo de esquema añadido durante ese flujo:

components:
  schemas:
    Invoice:
      type: object
      required: [id, amount, currency]
      properties:
        id:
          type: string
          format: uuid
        amount:
          type: integer
          description: Amount in the smallest currency unit
        currency:
          type: string
          example: USD
        status:
          type: string
          enum: [draft, sent, paid]

Este enfoque mantiene la especificación dentro del mismo ciclo que el código de aplicación: revisión, versionado, historial y colaboración mediante Git.

Quién debería usar el Modo Spec-First

Use Spec-First si su equipo:

• Ya trabaja diariamente con Git.
• Revisa contratos de API mediante pull requests.
• Quiere versionar OpenAPI junto al código del servicio.
• Prefiere editar YAML o JSON directamente.
• Trata la especificación como artefacto principal del desarrollo.

Es especialmente útil para:

• Equipos backend.
• Equipos de plataforma.
• Equipos API-first.
• Organizaciones con procesos estrictos de revisión de contratos.

Use Design-First si:

• Prefiere formularios visuales.
• Personas no técnicas participan activamente en el diseño.
• El equipo necesita una experiencia más guiada.
• Quiere evitar edición manual de YAML o JSON.

Si todavía no está seguro, revise la publicación comparativa.

Limitaciones y notas de la beta

Spec-First está en beta, así que conviene usarlo con expectativas realistas.

Puntos a considerar:

• El comportamiento puede cambiar mientras Apidog refina la funcionalidad.
• GitHub y GitLab tienen integración directa.
• Azure DevOps funciona mediante conexión Git genérica.
• Si depende de un flujo Git específico, pruébelo antes en un repositorio no crítico.
• La disciplina Git sigue siendo responsabilidad del equipo.

Recomendación práctica:

1. Cree un repositorio de prueba.
2. Conecte Apidog en modo Spec-First.
3. Ejecute un ciclo pequeño: editar, validar, commit, push.
4. Revise cómo se integra con su proceso de pull requests.
5. Solo después amplíe su uso a proyectos críticos.

La ventaja de una beta es que el feedback temprano puede influir en la evolución del producto.

Preguntas frecuentes

¿Es gratuito el Modo Spec-First?

El Modo Spec-First es una funcionalidad beta dentro de Apidog. El acceso depende de su plan y del estado beta disponible para su cuenta.

La forma más directa de comprobarlo es abrir el módulo de APIs y verificar si el cambio a Spec-First está disponible.

¿Qué proveedores Git son compatibles?

GitHub y GitLab son compatibles mediante integración directa.

Azure DevOps funciona mediante una Conexión Git genérica con credenciales Git estándar.

Otros hosts Git pueden funcionar mediante esa conexión genérica si son compatibles con el flujo Git estándar.

¿Puedo volver al Modo Design-First?

Sí. El selector de modo está en la parte inferior izquierda del módulo de APIs.

Puede alternar entre Spec-First y Design-First según el proyecto o el flujo de trabajo que necesite.

¿Qué formatos puedo editar?

Puede editar documentos OpenAPI en:

• YAML.
• JSON.

El editor ofrece resaltado de sintaxis, validación de esquema y autocompletado para OpenAPI y Swagger.

¿Qué sucede con mis ediciones no enviadas?

Las ediciones no enviadas permanecen locales hasta que haga push.

Apidog muestra los cambios como modificados, añadidos o eliminados. Si no quiere conservar una edición, puede descartarla antes de enviarla al repositorio.

Conclusión

El Modo Apidog Spec-First conecta edición OpenAPI y Git en un mismo flujo. Usted trabaja directamente sobre YAML o JSON, navega la especificación con un esquema auto-parseado, valida mientras escribe y sincroniza con GitHub, GitLab o Azure DevOps.

Si su equipo ya trata la especificación como código, Spec-First encaja bien: commit, push, historial, revisión y colaboración sobre el contrato API.

Para probarlo, habilite el modo en el módulo de APIs, conecte un repositorio y ejecute un ciclo pequeño de edición-confirmación-envío. Luego consulte la documentación del Modo Spec-First para avanzar con una configuración real.