Tu especificación OpenAPI es el contrato entre tu API y sus consumidores. Para que ese contrato sea útil, debe vivir donde el equipo ya revisa, versiona y despliega cambios: en Git.
Cuando la especificación vive en una herramienta aislada, es fácil que se desincronice: la documentación queda obsoleta, las colecciones de pruebas divergen y los reviewers aprueban código sin validar el cambio correspondiente en el contrato de API.
El Modo Spec-first cambia ese flujo: tus archivos OpenAPI o Swagger se almacenan en el repositorio junto al código. Cada cambio pasa por ramas, commits, pull requests y revisiones. El diseño de API, las pruebas y la documentación se mantienen sincronizados con la especificación.
En esta guía verás cómo crear un proyecto Spec-first en Apidog, editar archivos OpenAPI, validar cambios, sincronizar con Git y trabajar con ramas.
¿Qué es el Modo Spec-first?
En un proyecto de API tradicional, defines endpoints desde formularios visuales o importas una especificación inicial. La herramienta guarda la definición internamente y, si existe integración con Git, normalmente funciona como exportación.
En Modo Spec-first, el flujo está basado en archivos:
-
openapi.yamluopenapi.jsonviven en tu repositorio. - Apidog analiza esos archivos y genera una estructura navegable.
- Editas el archivo directamente o mediante formularios compatibles.
- Los cambios se sincronizan con Git.
El archivo de especificación sigue siendo la fuente de verdad. Apidog lo lee, lo escribe y lo mantiene alineado con el repositorio.
Requisitos previos
Antes de empezar, asegúrate de tener:
- Una cuenta de Apidog.
- Un repositorio Git con un archivo OpenAPI/Swagger, o un repositorio vacío.
- Permisos de escritura sobre el repositorio.
- Conocimiento básico de OpenAPI o Swagger.
Paso 1: Crear un proyecto Spec-first
En Apidog:
- Haz clic en + Nuevo Proyecto.
- Selecciona Modo Spec-first.
- Conecta tu proveedor Git:
- GitHub
- GitLab
- Azure DevOps
- Bitbucket
- Elige la organización o workspace.
- Selecciona un repositorio existente o crea uno nuevo.
- Selecciona la rama principal para sincronizar.
Apidog sincroniza con la rama predeterminada del repositorio. Si no se llama main, la detecta automáticamente.
Paso 2: Configurar la sincronización con webhook
Durante la configuración puedes instalar un webhook. Esto permite que Apidog sincronice automáticamente cuando alguien hace push al repositorio.
Nota: instalar el webhook normalmente requiere permisos de administrador en el repositorio. Si no los tienes, puedes omitir este paso y usar Git Pull manualmente.
Con webhook activo:
- El equipo hace push de cambios.
- Apidog recibe el evento.
- La especificación se actualiza automáticamente.
- Todos ven la versión más reciente.
Si omitiste este paso, puedes configurarlo después desde:
Configuración del proyecto > Git y Ramas
Paso 3: Explorar el workspace de Especificaciones
Después de crear el proyecto, Apidog abre el workspace de Especificaciones. Aquí editas archivos, navegas la estructura OpenAPI y ejecutas operaciones Git.
El workspace se divide en tres paneles:
| Panel | Qué muestra |
|---|---|
| Explorador de Archivos | Archivos y carpetas del repositorio sincronizado |
| Árbol de Estructura API | Endpoints, esquemas, definiciones y vista general extraídos desde OpenAPI |
| Editor | Edición en vista de código o vista de formulario |
Flujo recomendado:
- Selecciona un archivo OpenAPI en el explorador.
- Usa el árbol para ubicar un endpoint o schema.
- Haz clic en el nodo.
- Apidog resalta la sección correspondiente del YAML o JSON.
Esto te permite moverte entre una vista de alto nivel de la API y el archivo fuente sin cambiar de herramienta.
Paso 4: Editar archivos de especificación
Vista de Código: edición directa
Para YAML, JSON o Markdown, usa la Vista de código.
Ejemplo de endpoint OpenAPI:
paths:
/users/{id}:
get:
summary: Obtener usuario por ID
parameters:
- name: id
in: path
required: true
schema:
type: string
responses:
"200":
description: Usuario encontrado
Las ediciones se guardan en el archivo. Apidog no crea una copia paralela ni reemplaza el contrato por un formato interno.
Vista de Formulario: edición estructurada
Para nodos compatibles — endpoints, schemas, definiciones y vista general — puedes usar la Vista de formulario.
Úsala cuando quieras:
- Añadir endpoints sin memorizar toda la estructura YAML.
- Editar schemas visualmente.
- Actualizar metadatos de API.
- Configurar definiciones de seguridad.
Si un nodo no admite formulario, Apidog mantiene la edición en vista de código.
Paso 5: Validar y previsualizar cambios
El Modo Spec-first incluye validación y previsualización de documentación sin salir del editor.
Validar la especificación
Haz clic en Validación en el encabezado del editor.
El panel muestra advertencias y errores, por ejemplo:
- Errores de sintaxis.
- Campos obligatorios faltantes.
- Violaciones de schema.
- Problemas de convenciones de nombres.
Antes de hacer commit, revisa y corrige los errores. Así reduces el trabajo manual durante la revisión del pull request.
Previsualizar documentación
Haz clic en Previsualizar para ver cómo se renderiza la especificación como documentación de API.
Para endpoints, la vista previa incluye:
| Pestaña | Contenido |
|---|---|
| Docs | Documentación generada del endpoint |
| Pruébalo | Panel de solicitud en vivo basado en la definición del endpoint |
Para schemas y definiciones, la vista previa muestra la documentación renderizada.
La validación y la previsualización comparten el mismo panel lateral. Abrir uno cierra el otro.
Paso 6: Obtener cambios del equipo
Cuando otros colaboradores suben cambios al repositorio, sincronízalos en Apidog:
- Abre el workspace de Especificaciones.
- Haz clic en el nombre de la rama actual.
- Selecciona Git Pull.
Si el webhook está activo, Apidog hace pull automáticamente cuando detecta eventos de push.
Paso 7: Hacer commit y push de tus cambios
Después de editar la especificación:
- Abre Cambios en la barra lateral.
- Revisa archivos modificados, añadidos, renombrados o eliminados.
- Haz clic en Commit & Push.
- Selecciona los archivos que quieres incluir.
- Escribe un mensaje de commit.
- Haz clic en Push.
Ejemplo de mensaje de commit:
docs: update user endpoints OpenAPI spec
Tus cambios de especificación pasan al mismo flujo de pull request que el código. El equipo puede revisar implementación y contrato de API en un solo lugar.
Consejo: usa Descartar todos los cambios si quieres abandonar ediciones locales antes de hacer push.
Paso 8: Trabajar con ramas
El Modo Spec-first soporta colaboración basada en ramas. Apidog mapea ramas de Git a ramas del proyecto, lo que permite trabajar con múltiples versiones de la especificación.
Operaciones comunes:
| Acción | Cómo hacerlo |
|---|---|
| Cambiar de rama | Haz clic en el nombre de la rama y selecciona otra |
| Importar rama Git existente | Haz clic en Importar Nueva Rama, selecciona la rama e impórtala |
| Crear nueva rama | Ve a Configuración del Proyecto > Git y Ramas > Nueva Rama |
| Corregir problemas de sincronización | Usa Resincronizar en la configuración de la rama |
| Ver registros de sincronización | Acciones de rama > Ver Registros |
Puedes usar el mismo flujo que en Git:
- Ramas de feature.
- Ramas de release.
- Desarrollo paralelo.
- Revisión por pull request.
Paso 9: Integrar con CI/CD
Como la especificación vive en Git, puedes incluirla en tus pipelines.
Casos comunes:
- Ejecutar lint de OpenAPI en cada pull request.
- Generar documentación al fusionar en
main. - Ejecutar pruebas de API cuando cambia la especificación.
- Sincronizar con gateways, mock servers o generadores de SDK.
Ejemplo con 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
Con este flujo, la especificación pasa por las mismas puertas de calidad que el código de aplicación.
Alternativa: proyectos con respaldo de almacenamiento
Si todavía no quieres conectar un repositorio Git externo, Apidog también permite proyectos Spec-first con respaldo de almacenamiento.
Estos proyectos usan el almacenamiento interno de Apidog, pero mantienen capacidades como:
- Edición basada en archivos.
- Validación.
- Previsualización.
- Gestión de ramas.
La interfaz cambia ligeramente:
- Git Pull pasa a ser Sincronizar.
- Commit & Push pasa a ser Guardar.
Puedes empezar así y migrar a Git externo cuando tu equipo esté listo.
Resumen
Con el Modo Spec-first, tu flujo de trabajo cambia así:
| Antes de Spec-first | Después de Spec-first |
|---|---|
| Las especificaciones viven en una herramienta separada | Las especificaciones viven en tu repositorio Git |
| Exportas e importas para sincronizar | Sincronizas automáticamente en cada push |
| Las revisiones ocurren fuera del flujo de código | Las revisiones ocurren en pull requests |
| La documentación se genera por separado | La previsualizas mientras editas |
| Las pruebas están desconectadas de la especificación | Las pruebas pueden activarse por cambios en la especificación |
El Modo Spec-first convierte tus archivos OpenAPI en el contrato que deberían ser: versionados, revisados y alineados con el código.
Para empezar, crea un proyecto Spec-first en Apidog, conecta tu repositorio y convierte la especificación en parte real de tu flujo de desarrollo.
Top comments (0)