Tu código vive en Git. Tus pipelines de CI, revisiones e historial de lanzamientos viven en Git. Entonces, ¿por qué tu especificación de API vive en otro lugar?
Un flujo de trabajo de API nativo de Git mantiene tu definición de OpenAPI en el mismo lugar que tu código. Editas la especificación como un archivo YAML o JSON simple, lo confirmas (commit) y lo pasas por el mismo proceso de revisión que usas para todo lo demás. Sin bases de datos en la nube separadas. Sin bailes de exportación-importación. La especificación es solo otro archivo en tu repositorio.
Qué significa un flujo de trabajo de API nativo de Git
Un flujo de trabajo de API nativo de Git trata tu especificación de API como código. El archivo OpenAPI reside en un repositorio junto a tus servicios. Cada cambio es un commit. Cada commit tiene un autor, un mensaje y un diff.
Esto te da tres cosas que ya esperas del código fuente:
- Historial de versiones. Puedes ver quién cambió un endpoint y cuándo.
git blamefunciona en tu especificación. - Ramificación y revisión. Los cambios en la especificación pasan por solicitudes de extracción (pull requests). Los revisores ven el diff exacto antes de que se fusione nada.
- Una única fuente de verdad. El archivo en
maines el contrato. Herramientas, documentos y simulaciones leen de él.
Esta es la idea central detrás de un flujo de trabajo de API spec-first: la especificación lidera y la implementación sigue. Para una mirada más profunda a esta práctica, consulta nuestra guía sobre el desarrollo de API spec-first.
El enfoque opuesto almacena tu especificación dentro de una aplicación en la nube propietaria. Eso funciona hasta que tu equipo crece o tu proceso madura. Entonces aparecen las grietas.
El problema con las especificaciones de API bloqueadas en la nube
La mayoría de las herramientas de diseño de API mantienen la especificación en su propia base de datos. Editas a través de su interfaz de usuario. El "archivo" que crees poseer es en realidad una fila en el sistema de otra persona.
Esto se descompone de maneras predecibles.
La revisión ocurre en dos lugares. Los cambios de código pasan por GitHub. Los cambios de especificación pasan por una herramienta separada con sus propios comentarios e historial. Los revisores cambian de contexto. Las aprobaciones se desfasan.
El diff está oculto. Cuando la especificación vive en una base de datos en la nube, no puedes ver una diferencia limpia línea por línea en tu solicitud de extracción. Apruebas una "v3 del diseño" sin tener idea de lo que realmente cambió.
La exportación se convierte en una tarea. Para llevar la especificación a CI, la exportas, confirmas la exportación y esperas que nadie haya editado la copia en la nube mientras tanto. Dos fuentes de verdad, un conflicto inevitable.
La automatización te combate. Los linters, las pruebas de contrato y los generadores de código quieren un archivo en el disco. Una especificación bloqueada en la nube fuerza un paso de obtención antes de que se ejecute cualquiera de ellos.
Tratar tu especificación de API como código elimina todo esto. El archivo es la especificación. Git es el historial. Tu pipeline existente hace el resto. Cubrimos el principio en detalle en la especificación de API como código.
Cómo funciona el Modo Spec-First de Apidog
El Modo Spec-First está diseñado para equipos que ya piensan en commits y ramas. Diseñas la API como archivos YAML o JSON puros, y Apidog mantiene esos archivos sincronizados con tu repositorio Git en ambas direcciones.
Esto es lo que obtienes.
Un editor OpenAPI estilo IDE
Escribes la especificación en un editor de código, no en un formulario. El editor ofrece las comodidades que esperarías de un IDE:
- Resaltado de sintaxis para YAML y JSON.
- Validación contra los esquemas OpenAPI y Swagger, para que los errores aparezcan mientras escribes.
- Autocompletado para palabras clave, tipos y referencias de OpenAPI.
Mantienes el control exacto del archivo. Sin campos ocultos, sin metadatos solo de la interfaz de usuario.
Archivos YAML/JSON puros
La especificación es un archivo real. Una pequeña porción de uno:
openapi: 3.1.0
info:
title: Orders API
version: 1.2.0
paths:
/orders/{orderId}:
get:
summary: Get an order by ID
operationId: getOrder
parameters:
- name: orderId
in: path
required: true
schema:
type: string
responses:
"200":
description: Order found
content:
application/json:
schema:
$ref: "#/components/schemas/Order"
"404":
description: Order not found
components:
schemas:
Order:
type: object
properties:
id:
type: string
status:
type: string
enum: [pending, shipped, delivered]
Este es el archivo que llega a tu repositorio. Lo que editas es lo que se confirma.
Un esquema navegable auto-analizado
Mientras escribes, Apidog analiza el archivo y construye un esquema visual en la barra lateral izquierda. Las rutas, operaciones y esquemas aparecen como un árbol por el que puedes hacer clic. Obtienes la legibilidad de una herramienta de diseño y la precisión de los archivos sin procesar al mismo tiempo.
Las especificaciones largas se mantienen navegables. Salta a un endpoint sin desplazarte por cientos de líneas.
Sincronización Git bidireccional
El Modo Spec-First se conecta a tu proveedor de Git y sincroniza los cambios en ambas direcciones. Es compatible directamente con GitHub y GitLab, y con Azure DevOps a través de una Conexión Git.
Obtén los cambios que tus compañeros de equipo enviaron. Edita localmente en el editor de Apidog. Luego, confirma y envía de vuelta a la misma rama. El repositorio y tu espacio de trabajo se mantienen alineados.
Confirmar, enviar y un indicador de estado de sincronización
No sales de Apidog para gestionar Git. Prepara tus cambios, escribe un mensaje de commit y envíalos (push). Un indicador de estado de sincronización te dice dónde te encuentras. Después de un push exitoso, dice algo como "Sincronizado ahora mismo". Si cambias de opinión antes de hacer push, puedes descartar las ediciones no enviadas y volver al último estado sincronizado.
Esta sincronización bidireccional es el corazón del flujo de trabajo de API nativo de Git. Para una guía enfocada en el lado de GitHub, consulta sincronizar la especificación OpenAPI con GitHub.
Guía de configuración
Aquí te explicamos cómo pasar de un repositorio vacío a una especificación sincronizada. La referencia completa se encuentra en la documentación del Modo Spec-First.
- Crea un proyecto desde un repositorio. En Apidog, inicia un nuevo proyecto Spec-First y conecta tu proveedor de Git. Elige el repositorio que contiene tu especificación de API y selecciona la rama a seguir, generalmente
main. Apidog extrae los archivos de especificación existentes al editor.
- Edita la especificación. Abre el archivo OpenAPI en el editor. Agrega un endpoint, ajusta un esquema o corrige una respuesta. El resaltado de sintaxis, la validación y el autocompletado te guían mientras escribes. El esquema de la barra lateral izquierda se actualiza a medida que cambia el archivo.
- Rastrea archivos modificados, agregados y eliminados. Apidog muestra qué archivos has cambiado desde la última sincronización. Los archivos modificados, agregados y eliminados se marcan para que sepas exactamente lo que está a punto de entrar en el commit.
- Escribe un mensaje de commit. Describe el cambio en lenguaje sencillo, de la misma manera que lo harías en cualquier cliente de Git. "Agregar respuesta 404 a getOrder" es mejor que "actualizar especificación".
- Push. Envía el commit a la rama rastreada. Tus compañeros de equipo y tu pipeline de CI ahora ven la nueva versión.
- Verifica "Sincronizado ahora mismo". Observa el indicador de estado de sincronización confirmar el push. Cuando dice "Sincronizado ahora mismo", tus ediciones locales y la rama remota coinciden. Desde aquí, el cambio fluye a través de tu proceso normal de solicitud de extracción y revisión.
Ese es el ciclo completo: pull, editar, commit, push, verificar. Sin paso de exportación. Sin una segunda fuente de verdad.
Modo Spec-First vs. Modo Design-First
Apidog admite dos formas de trabajar. La diferencia está en dónde reside la especificación y cómo la editas.
| Modo Spec-First (beta) | Modo Design-First | |
|---|---|---|
| Almacenamiento de la especificación | Archivos YAML/JSON puros en Git | Proyecto en la nube de Apidog |
| Editor principal | Editor de código estilo IDE | Interfaz de usuario visual basada en formularios |
| Control de versiones | Git nativo (commits, ramas, diffs) | Historial y ramas de Apidog |
| Sincronización Git bidireccional | Sí (GitHub, GitLab, Azure DevOps) | Vía exportación/importación |
| Ideal para | Equipos que viven en Git | Equipos que prefieren un flujo de trabajo visual |
Ningún modo es "mejor". Sirven a hábitos diferentes. Si tu proceso de revisión y lanzamiento ya se ejecuta en Git, el Modo Spec-First elimina la fricción. Si tu equipo diseña visualmente y rara vez toca OpenAPI en crudo, el Modo Design-First podría ajustarse mejor.
Cuándo usarlo
Utiliza el Modo Spec-First cuando:
- Tu especificación debe pasar por solicitudes de extracción y revisión de código.
- Quieres
git blamey un historial de commits real en tu contrato de API. - Tu CI ejecuta linting de especificaciones, pruebas de contrato o generación de código que necesitan un archivo en disco.
- Múltiples ingenieros editan la especificación y quieres diffs limpios y fusionables.
- Estás cansado de exportar de una herramienta para alimentar otra.
Mantente con un enfoque visual y en la nube cuando tu equipo diseñe APIs sin escribir OpenAPI en bruto, o cuando no ingenieros sean los propietarios de la especificación y prefieran un editor basado en formularios.
Preguntas Frecuentes
¿Qué es un flujo de trabajo de API nativo de Git?
Un flujo de trabajo de API nativo de Git almacena tu especificación OpenAPI como un archivo en un repositorio Git y gestiona cada cambio a través de commits, ramas y solicitudes de extracción. La especificación sigue el mismo proceso de revisión y control de versiones que el código de tu aplicación, por lo que hay una única fuente de verdad.
¿El Modo Spec-First de Apidog es compatible con GitHub y GitLab?
Sí. El Modo Spec-First se sincroniza bidireccionalmente con GitHub y GitLab directamente. Azure DevOps es compatible a través de una conexión Git. Conectas el repositorio, eliges una rama y Apidog mantiene tus ediciones y el remoto sincronizados.
¿Puedo editar archivos OpenAPI como YAML o JSON en bruto?
Sí. El Modo Spec-First te ofrece un editor estilo IDE para YAML y JSON en bruto, con resaltado de sintaxis, validación de esquemas y autocompletado para OpenAPI y Swagger. Un esquema en la barra lateral izquierda analiza automáticamente el archivo para que puedas navegar rápidamente por especificaciones grandes.
¿Cuál es la diferencia entre el Modo Spec-First y el Modo Design-First?
El Modo Spec-First mantiene tu especificación como archivos en Git y los edita en un editor de código con sincronización bidireccional. El Modo Design-First mantiene la especificación en un proyecto en la nube de Apidog con un editor visual basado en formularios. Elige Spec-First si tu flujo de trabajo ya se ejecuta en Git.
Conclusión
Un flujo de trabajo de API nativo de Git pone fin a la división entre tu código y tu contrato de API. La especificación se convierte en un archivo, el archivo se convierte en un commit y el commit fluye a través del proceso de revisión en el que ya confías.
El Modo Spec-First de Apidog te ofrece el editor estilo IDE, el esquema navegable y la sincronización Git bidireccional para hacerlo realidad. Editas YAML o JSON en bruto, confirmas un mensaje claro, haces push y observas cómo el estado dice "Sincronizado ahora mismo".
Prueba el Modo Spec-First y trae tu especificación de API a casa, a Git.