Colaboración Git para Testing y Desarrollo de APIs

Tu especificación OpenAPI es el contrato entre tu API y sus consumidores. Pero, ¿dónde reside ese contrato?

Con demasiada frecuencia, las especificaciones de API residen en herramientas aisladas, se exportan una vez, se olvidan y rara vez se actualizan cuando la implementación cambia. La documentación se desincroniza. Las colecciones de pruebas divergen. Los revisores aprueban cambios de código sin ver nunca las actualizaciones correspondientes de la especificación.

El Modo Spec-first invierte este modelo. Tus archivos OpenAPI o Swagger se convierten en la fuente de la verdad, almacenados directamente en tu repositorio Git junto con el código de implementación. Cada cambio en la especificación fluye a través de las mismas ramas, solicitudes de extracción (pull requests) y proceso de revisión que ya utilizas. El diseño de API, las pruebas y la documentación se mantienen sincronizados automáticamente.

En este tutorial, te guiaré a través de la configuración de un proyecto Spec-first en Apidog, la edición de especificaciones con tu equipo y cómo mantener todo sincronizado con tu flujo de trabajo Git.

¿Qué es el Modo Spec-first?

En un proyecto de API típico, creas endpoints a través de formularios visuales o importas especificaciones existentes como punto de partida. La herramienta almacena las definiciones de API internamente, y la integración con Git (si está disponible) es un paso de exportación.

El Modo Spec-first es diferente. El espacio de trabajo principal está basado en archivos:

• openapi.yaml o openapi.json residen en tu repositorio
• Apidog analiza estos archivos y genera una estructura API navegable
• Editas los archivos directamente (o a través de formularios soportados)
• Los cambios se sincronizan automáticamente con Git

El archivo de especificación es siempre la autoridad. Apidog lo lee, lo escribe y lo mantiene sincronizado con tu repositorio.

Requisitos previos

Para seguir este tutorial, necesitarás:

• Una cuenta de Apidog (el nivel gratuito funciona)
• Un repositorio Git con un archivo OpenAPI/Swagger, o un repositorio vacío para empezar de nuevo
• Acceso de escritura al repositorio
• Familiaridad básica con la sintaxis de OpenAPI o Swagger

Paso 1: Crear un proyecto Spec-first

Haz clic en + Nuevo Proyecto en Apidog y elige Modo Spec-first como tipo de proyecto.

A continuación, conecta tu proveedor Git:

1. Selecciona tu proveedor (GitHub, GitLab, Azure DevOps o Bitbucket)
2. Elige una organización o espacio de trabajo
3. Selecciona un repositorio existente o crea uno nuevo
4. Selecciona la rama principal para la sincronización

Apidog se sincronizará con la rama predeterminada de tu repositorio. Si no se llama main, Apidog se adapta automáticamente.

Paso 2: Configurar la sincronización con Webhook (Recomendado)

Durante la configuración, verás una opción para instalar un webhook. Esto permite la sincronización automática cada vez que tu equipo realiza un push al repositorio.

Nota: La instalación del webhook generalmente requiere permisos de administrador en el repositorio. Si no tienes acceso de administrador, omite este paso; aún puedes sincronizar manualmente usando Git Pull.

Beneficios del webhook:

• El equipo hace un push de cambios → Apidog sincroniza automáticamente
• No es necesario actualizar manualmente
• Todos ven el estado más reciente de la especificación

Si omitiste la configuración del webhook inicialmente, puedes añadirlo más tarde desde Configuración del proyecto > Git y Ramas.

Paso 3: Explorar el espacio de trabajo de Especificaciones

Después de la creación, tu proyecto abre el espacio de trabajo de Especificaciones, el centro principal para la edición basada en archivos y las operaciones Git.

Tres paneles trabajan juntos:

Haz clic en un endpoint en el árbol de estructura → Apidog resalta la sección correspondiente en tu archivo fuente. Navega desde la vista de API de alto nivel hasta el YAML de bajo nivel sin cambiar de pestaña.

Paso 4: Editar tus archivos de especificación

Vista de Código: Edición Directa

Para la mayoría de los archivos — YAML, JSON, Markdown — usa la Vista de código para editar el texto sin formato.

Tus ediciones permanecen en el archivo. Apidog no las transforma ni las almacena por separado. El archivo de especificación sigue siendo la única fuente de verdad.

Vista de Formulario: Edición Estructurada

Para los nodos OpenAPI compatibles — endpoints, esquemas, definiciones y vista general de la API — cambia a la Vista de formulario.

La vista de formulario es útil cuando:

• Añades endpoints con todos los campos requeridos sin memorizar la estructura YAML
• Editas esquemas visualmente
• Actualizas definiciones de seguridad y metadatos de API

Si un nodo no admite la edición de formularios, Apidog te mantiene en la vista de código.

Paso 5: Validar y Previsualizar al Instante

El Modo Spec-first incluye validación en tiempo real y vista previa de la documentación, sin necesidad de herramientas externas.

Verificar problemas con la validación

Haz clic en Validación en el encabezado del editor. Un panel muestra todas las advertencias y errores en tu especificación actual.

La insignia muestra el número total de problemas. Captura:

• Errores de sintaxis
• Campos obligatorios faltantes
• Violaciones de esquema
• Problemas de convención de nomenclatura

Corrige los problemas antes de confirmar. Los revisores de tu equipo no necesitarán detectarlos manualmente.

Previsualiza tu documentación

Haz clic en Previsualizar para ver cómo tu especificación se renderiza como documentación de API.

Para los endpoints, la vista previa incluye dos pestañas:

Para esquemas y definiciones, la vista previa muestra la vista de documentación renderizada.

La validación y la previsualización comparten el mismo panel lateral. Abrir uno cierra automáticamente el otro.

Paso 6: Obtener actualizaciones de tu equipo

Cuando los colaboradores suben cambios a tu repositorio, impórtalos en Apidog:

1. Abre el espacio de trabajo de Especificaciones
2. Haz clic en el nombre de la rama actual en la barra lateral
3. Selecciona Git Pull

Si la sincronización con webhook está activa, Apidog realiza el pull automáticamente en los eventos de push del repositorio, sin necesidad de pasos manuales.

Paso 7: Realizar Commit y Push de tus Cambios

Después de editar archivos en Apidog, envía tus actualizaciones a Git:

1. Realiza cambios en el espacio de trabajo de Especificaciones
2. Haz clic en Cambios en la barra lateral para ver los archivos modificados, añadidos, renombrados y eliminados
3. Haz clic en Commit & Push
4. Selecciona qué archivos incluir
5. Escribe un mensaje de commit
6. Haz clic en Push

Tus actualizaciones de especificación ahora aparecen en el mismo flujo de trabajo de pull request que tus cambios de código. Tus compañeros de equipo pueden revisar, comentar y aprobar, tanto la implementación como el contrato de API en un solo lugar.

Consejo: Usa Descartar todos los cambios si quieres abandonar las ediciones locales antes de hacer push.

Paso 8: Trabajar con Ramas

El Modo Spec-first es compatible con la colaboración completa basada en ramas. Apidog mapea las ramas de Git a las ramas del proyecto, permitiéndote cambiar entre versiones de especificación.

Operaciones comunes de ramas

La gestión de ramas funciona de la misma manera que esperas de Git: ramas de características, lanzamientos y desarrollo paralelo se sincronizan correctamente.

Paso 9: Integrar con CI/CD

Dado que tus especificaciones residen en Git, encajan naturalmente en las tuberías de automatización:

• Lint de especificaciones en cada PR usando la validación de Apidog o herramientas como Spectral
• Generar documentación automáticamente cuando las especificaciones se fusionan a `main`
• Ejecutar pruebas de API activadas por cambios en la especificación
• Sincronizar con sistemas posteriores — gateways de API, servidores de prueba, generadores de SDK

Ejemplo de flujo de trabajo de GitHub Actions:

name: Validate and Test API Spec

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Lint OpenAPI Spec
        run: npx spectral lint openapi.yaml

      - name: Run API Tests
        run: apidog run tests --spec openapi.yaml

Tus especificaciones de API ahora pasan por las mismas puertas de calidad que el código de tu aplicación.

Alternativa: Proyectos con respaldo de almacenamiento

Si no estás listo para conectar un repositorio Git externo, Apidog ofrece proyectos Spec-first con respaldo de almacenamiento.

Estos proyectos utilizan el almacenamiento interno de Apidog, pero aun así proporcionan:

• Edición basada en archivos
• Validación y vista previa
• Gestión de ramas

Las etiquetas de la interfaz de usuario se ajustan ligeramente:

• Git Pull se convierte en Sincronizar
• Commit & Push se convierte en Guardar

Migra a Git externo cuando tu equipo esté listo.

Resumen

Con el Modo Spec-first, tu flujo de trabajo de API se convierte en:

El Modo Spec-first convierte los archivos OpenAPI en el contrato que deberían ser: versionados, revisados y siempre alineados con tu código.

¿Listo para probarlo? Crea un proyecto Spec-first en Apidog y conecta tu primer repositorio.