Modo Spec-first (Beta)

El Modo Spec-first es para equipos que desean que los archivos de especificación de API sean la fuente de verdad. En este modo, usted diseña y mantiene archivos OpenAPI o Swagger directamente en Apidog, previsualiza la documentación de API generada mientras edita y mantiene los archivos sincronizados con Git.

Use el Modo Spec-first cuando su equipo ya trabaje con archivos de especificación YAML o JSON, revise cambios de API mediante Git o desee que el diseño de API encaje de forma natural en un flujo de trabajo de repositorio de código.

Cómo funciona el Modo Spec-first

En un proyecto normal de Apidog, las API suelen crearse y editarse mediante formularios visuales. En un proyecto Spec-first, el espacio de trabajo principal se basa en archivos.

Usted trabaja con archivos como:

openapi.yaml

openapi.json

Archivos Swagger 2.0

Archivos Markdown y otros archivos de apoyo del proyecto

Apidog analiza los archivos de especificación y los convierte en una estructura de API navegable. Puede editar los archivos sin procesar, usar formularios visuales compatibles, validar la especificación, previsualizar la documentación generada y enviar los cambios de vuelta a Git.

Crear un proyecto Spec-first

Haga clic en + New Project.

En el selector de tipo de proyecto, elija Spec-first Mode.

Conecte un proveedor de Git, como GitHub, GitLab, Azure DevOps o Bitbucket.

Seleccione una organización o un espacio de trabajo y, a continuación, elija un repositorio existente o cree un repositorio nuevo si la opción está disponible.

Seleccione la rama principal con la que Apidog debe sincronizarse.

Elija si desea instalar un webhook.

Instalar un webhook permite que los pushes en el repositorio de Git activen la sincronización automática. Normalmente, esto requiere permiso de administrador en el repositorio. Si no tiene permiso de administrador, puede omitir la instalación del webhook y sincronizar manualmente.

Introduzca el nombre del proyecto, configure los permisos de los miembros y haga clic en Create.

Después de la creación, Apidog realiza la primera sincronización. Si la rama predeterminada del repositorio no es main, Apidog usa el nombre de la rama del repositorio para la rama principal del proyecto.

Los proyectos Spec-first no incluyen datos de proyecto de ejemplo. El contenido de la API proviene de sus archivos de especificación.

El espacio de trabajo Specs

Los proyectos Spec-first incluyen un espacio de trabajo Specs en la barra lateral izquierda. Este es el lugar principal para gestionar archivos de especificación y la sincronización con Git.

El espacio de trabajo contiene tres áreas principales:

Explorador de archivos: Explore y gestione archivos y carpetas del repositorio sincronizado.

Árbol de estructura de API: Navegue por el contenido OpenAPI analizado, como la vista general, endpoints, esquemas y definiciones.

Editor: Edite archivos en la vista de código o, para nodos OpenAPI compatibles, en la vista de formulario.

Cuando selecciona un endpoint, esquema u otro nodo compatible en el árbol de estructura, Apidog abre la parte relacionada del archivo de origen. Esto le permite moverse entre la vista a nivel de archivo y la vista a nivel de API sin salir del espacio de trabajo Specs.

Editar archivos de especificación

El editor admite diferentes tipos de archivo y modos de edición.

Vista de código

Use la vista Code para editar directamente archivos YAML, JSON, Markdown y otros archivos de texto. Esta es la forma predeterminada de trabajar en el Modo Spec-first.

Vista de formulario

Para nodos OpenAPI compatibles, Apidog también proporciona una vista Form. Esto le permite editar campos comunes de API mediante controles estructurados, manteniendo el archivo de especificación subyacente como la fuente de verdad.

La vista de formulario está disponible para nodos compatibles como:

Vista general de la API

Endpoints

Esquemas

Definiciones

Si el archivo o nodo seleccionado no puede editarse en la vista de formulario, Apidog lo mantiene en la vista de código.

Validar y previsualizar mientras edita

El Modo Spec-first incluye herramientas de validación y previsualización en el encabezado del editor.

Validación

El panel Validation muestra los problemas detectados en la especificación actual, incluidas advertencias y errores. La insignia de validación muestra el número total de problemas detectados.

Use este panel para encontrar problemas de sintaxis, campos obligatorios faltantes e infracciones de reglas antes de confirmar cambios.

Previsualización

El panel Preview muestra cómo aparecerá el nodo de especificación seleccionado en la documentación de API generada.

Previsualización está disponible para:

Vista general de la API

Endpoints

Esquemas

Definiciones

Para endpoints, Preview incluye:

Docs: La documentación de endpoint generada.

Try it out: Un panel de petición para enviar una petición basada en la definición del endpoint seleccionado.

Para esquemas, definiciones y nodos de vista general, Preview muestra la vista de documentación generada.

Validation y Preview usan el mismo panel lateral. Abrir uno cierra el otro.

Sincronizar cambios desde Git

Cuando otros miembros del equipo envían cambios al repositorio conectado, usted puede traer los archivos más recientes a Apidog.

Abra el espacio de trabajo Specs.

Haga clic en el nombre de la rama actual en la barra lateral de Specs.

Haga clic en Git Pull.

Si la sincronización mediante webhook está instalada, Apidog también puede recibir eventos push del proveedor de Git y activar la sincronización automáticamente.

Confirmar y enviar cambios a Git

Después de editar archivos en Apidog, envíe sus cambios de vuelta al repositorio conectado.

Edite uno o más archivos en el espacio de trabajo Specs.

Haga clic en Changes para revisar archivos modificados, añadidos, renombrados y eliminados.

Haga clic en Commit & Push.

En el modal Push to Git repo, seleccione los archivos que desea incluir.

Introduzca un mensaje de commit.

Haga clic en Push.

Si no desea conservar sus ediciones locales, use Discard all changes antes de enviar.

Gestionar ramas

El Modo Spec-first admite la colaboración basada en ramas. Apidog asigna las ramas de Git sincronizadas a ramas de proyecto para que usted pueda cambiar entre versiones de la especificación.

Cambiar de rama

Haga clic en el nombre de la rama en la barra lateral de Specs y seleccione otra rama en el menú desplegable.

Realizar seguimiento de una rama de Git existente

Si una rama existe en Git pero no se ha importado a Apidog, haga clic en Import New Branch, seleccione la rama e impórtela. Apidog empezará entonces a realizar el seguimiento y la sincronización de esa rama.

Crear una rama

Abra Project Settings > Git & Branches y haga clic en New Branch para crear una rama a partir de una rama de proyecto existente.

Resincronizar una rama

Si la sincronización de una rama falla o los archivos parecen estar desactualizados, use Re-sync en Project Settings > Git & Branches. Esto restablece el estado de sincronización de esa rama e importa los archivos de nuevo.

Ver registros de sincronización

Si una sincronización falla, abra las acciones de la rama y elija View Logs para inspeccionar los detalles de la sincronización.

Dejar de realizar seguimiento o eliminar una rama

Eliminar una rama con seguimiento la elimina de la configuración de sincronización de Apidog. Para ramas no principales, el registro de la rama del proyecto también puede eliminarse.

Sincronización mediante webhook y permisos

La sincronización mediante webhook es opcional, pero se recomienda para equipos que desean que Apidog se mantenga actualizado con los pushes del repositorio.

Cuando la sincronización mediante webhook está habilitada:

Apidog registra un webhook en el proveedor de Git conectado.

Solo se procesan los eventos push compatibles.

Apidog verifica la firma o el token del webhook antes de sincronizar.

Requisitos de permisos:

Instalar un webhook normalmente requiere permiso de administrador del repositorio.

Enviar cambios requiere permiso de escritura.

Si se omite la instalación del webhook, la sincronización manual sigue estando disponible.

Si omitió la instalación del webhook durante la creación del proyecto, puede instalarlo más tarde desde Project Settings > Git & Branches.

Proyectos Spec-first respaldados por almacenamiento

Algunos proyectos Spec-first pueden usar el almacenamiento interno de Apidog en lugar de un repositorio de Git externo.

Estos proyectos siguen usando el espacio de trabajo Specs, edición basada en archivos, validación, previsualización y gestión de ramas.

Las etiquetas de la interfaz de usuario son ligeramente diferentes:

Git Pull aparece como Sync.

Commit & Push aparece como Save.

La información del proveedor de Git y la configuración de webhook externo están ocultas.

Notas y limitaciones

El Modo Spec-first está actualmente en beta.

El espacio de trabajo Specs aparece solo en proyectos Spec-first.

Los proyectos Spec-first no crean datos de API de ejemplo.

El archivo de especificación es la fuente de verdad. Los cambios deben realizarse mediante el espacio de trabajo Specs o sincronizarse mediante Git.

La instalación del webhook puede fallar si no tiene permisos suficientes en el repositorio. Aun así, puede usar la sincronización manual si tiene acceso de escritura.

Modo Spec-first (Beta)

Cómo funciona el Modo Spec-first#

Crear un proyecto Spec-first#

El espacio de trabajo Specs#

Editar archivos de especificación#

Vista de código#

Vista de formulario#

Validar y previsualizar mientras edita#

Validación#

Previsualización#

Sincronizar cambios desde Git#

Confirmar y enviar cambios a Git#

Gestionar ramas#

Cambiar de rama#

Realizar seguimiento de una rama de Git existente#

Crear una rama#

Resincronizar una rama#

Ver registros de sincronización#

Dejar de realizar seguimiento o eliminar una rama#

Sincronización mediante webhook y permisos#

Proyectos Spec-first respaldados por almacenamiento#

Notas y limitaciones#