Cómo migrar de Stoplight a Apidog (Flujo de trabajo Spec-First)

Si está migrando de Stoplight Studio o Stoplight Platform a Apidog, lo primero que debe saber es que no necesita volver a cargar sus especificaciones OpenAPI. El Modo Spec-First de Apidog (actualmente en beta) se conecta directamente a su repositorio de GitHub o GitLab existente, por lo que Git sigue siendo la fuente de la verdad y su historial de commits permanece intacto. Esta guía detalla cada paso: exportar su configuración de Stoplight, mapear sus convenciones de directorio a las expectativas de Apidog y reemplazar .stoplight.json y toc.json con sus equivalentes de Apidog.

Equipos como los del Foro Económico Mundial ya gestionan las especificaciones OpenAPI en Git junto con Stoplight para la documentación. Si esa es su configuración, esta guía está escrita para usted. Y si todavía está sopesando opciones en lugar de comprometerse con una migración, la publicación sobre las principales alternativas a Stoplight Studio cubre el panorama más amplio.

Qué permanece igual al migrar

Sus archivos OpenAPI, su repositorio Git y su estrategia de ramas no cambian. Esa es la premisa clave. Stoplight almacena las especificaciones como archivos YAML o JSON registrados en el control de código fuente. Apidog lee esos mismos archivos cuando conecta un repositorio en el Modo Spec-First.

Lo que sí cambia es todo lo que está superpuesto: el renderizador de documentación, el servidor de simulacros (mock server), el ejecutor de pruebas y el cliente API. En lugar de que Stoplight Platform sirva la documentación y Postman maneje las pruebas como una herramienta separada, Apidog combina todo eso en un solo espacio de trabajo, sincronizado con el mismo archivo OpenAPI que sus ingenieros ya están comprometiendo.

La consecuencia práctica: su migración es principalmente un intercambio de configuración, no una migración de datos.

Paso 1: Exporte los activos de su proyecto Stoplight

Antes de tocar Apidog, capture todo lo que Stoplight contiene y que aún no está en Git.

Si usa Stoplight Studio con un backend de Git:

Sus especificaciones OpenAPI, modelos JSON Schema y documentación Markdown ya están confirmados. Ejecute un git pull para asegurarse de que su clon local esté actualizado. Stoplight sigue el formato de la Especificación OpenAPI, y esos archivos de especificación funcionan en Apidog sin necesidad de conversión. La estructura de su repositorio probablemente se vea así:

your-api-repo/
  .stoplight.json          # Configuración del proyecto (necesita reemplazo)
  reference/
    petstore.yaml          # Sus especificaciones OpenAPI
  models/
    error.json             # Modelos compartidos de JSON Schema
  docs/
    introduction.md        # Páginas de guía en Markdown
    authentication.md
  toc.json                 # Orden de la tabla de contenido (necesita reemplazo)
  assets/
    images/
      architecture.png

Si usa Stoplight Platform (alojado en la nube, sin backend de Git):

Exporte sus especificaciones desde la UI de Stoplight: abra cada proyecto API, vaya a "Exportar" y descargue el OpenAPI YAML. Para la documentación Markdown, cópiela en una carpeta docs/ en un nuevo repositorio Git. Stoplight no ofrece una exportación masiva para proyectos que no son de Git, así que haga esto por cada proyecto API.

Una vez que sus archivos estén en un repositorio Git (GitHub o GitLab), continúe con el siguiente paso.

Paso 2: Entienda los archivos de configuración que está reemplazando

Dos archivos específicos de Stoplight impulsan la estructura del proyecto. Ninguno tiene una contraparte directa en Apidog, pero entender lo que hacen le indica exactamente qué configurar en Apidog en su lugar.

La clave: .stoplight.json y toc.json son propiedad de Stoplight. Puede dejarlos en el repositorio (Apidog ignora los archivos desconocidos), pero no impulsarán nada en Apidog. Las configuraciones equivalentes se configuran a través de la UI del proyecto Apidog.

Paso 3: Conecte su repositorio al Modo Spec-First de Apidog

El Modo Spec-First de Apidog es cómo vincular un repositorio de GitHub o GitLab a un proyecto de Apidog para que la especificación OpenAPI siempre se lea desde Git, no desde una base de datos interna de Apidog. Esto mantiene a Git como la fuente autorizada, y significa que sus ingenieros pueden seguir enviando PRs para actualizar la especificación exactamente como lo hacen hoy.

Aquí está el flujo de conexión. También puede revisar la documentación de GitHub sobre cómo conectar aplicaciones de terceros a repositorios si tiene dudas sobre la concesión de permisos de OAuth.

1. En Apidog, cree un nuevo proyecto en Modo Spec-First.
2. Autentique Apidog con su cuenta de GitHub o GitLab y seleccione el repositorio.

3.Establezca la rama: use su rama predeterminada (main o master) para especificaciones de producción, o una rama de características durante las pruebas de migración.

1. Guardar. Apidog lee la especificación y construye la documentación interactiva, los puntos finales del servidor simulado y el andamiaje de prueba a partir de ella.

Si su especificación utiliza $ref para extraer esquemas del directorio models/, Apidog resuelve esas referencias en relación con la ubicación del archivo de especificación. No se necesita configuración adicional siempre que las rutas en su archivo OpenAPI sean correctas. Para una mirada más profunda sobre cómo funciona esta sincronización de Git, la guía para sincronizar especificaciones OpenAPI con GitHub cubre la mecánica en detalle.

Paso 4: Migre su documentación Markdown

Stoplight le permite mezclar páginas de guía Markdown con documentos de referencia API en una sola barra lateral. Apidog hace lo mismo a través de su editor de documentación.

Después de conectar su repositorio, importe sus archivos Markdown de docs/:

1. En el proyecto Apidog, abra la sección Docs.
2. Use Importar > Markdown y cargue sus archivos, o pegue el contenido página por página.

Para los activos de imagen referenciados en su Markdown (la carpeta assets/images/ en un diseño típico de Stoplight), cárguelos al almacenamiento de archivos de Apidog y actualice las referencias ![alt](path) en cada página. Si sus imágenes ya están alojadas en un CDN o una URL pública, no necesita cambiar nada.

Paso 5: Reemplace el servidor de simulacros de Stoplight

Stoplight Studio incluye un servidor de simulacros (mock server) local que lee su especificación OpenAPI y devuelve respuestas de ejemplo. El servidor de simulacros de Apidog hace lo mismo, pero está alojado en la nube y es accesible para todo su equipo sin necesidad de ejecutar un proceso local.

Una vez que su especificación esté conectada a través del Modo Spec-First, Apidog genera automáticamente puntos finales de simulacro para cada operación definida en su archivo OpenAPI. Las respuestas de ejemplo provienen del campo examples en su especificación, o del motor de simulacros inteligente de Apidog si no se define ningún ejemplo. Puede anular las reglas de respuesta por punto final dentro de Apidog sin tocar el archivo de especificación.

Para un equipo acostumbrado a ejecutar stoplight mock reference/your-api.yaml localmente, el cambio es que sus ingenieros de QA y desarrolladores frontend ahora acceden a una URL compartida en la nube. Esto merece validación en una prueba para confirmar que se ajusta a sus políticas de acceso a la red.

Paso 6: Reconstruya sus conjuntos de pruebas

Si usó las pruebas de contrato de Stoplight o las reglas de Spectral para el linting, estas necesitan un manejo separado.

Reglas de linting de Spectral: Stoplight usa Spectral para el linting de OpenAPI, configurado a través de un archivo .spectral.yaml. Apidog tiene sus propias reglas de linting incorporadas para el cumplimiento de OpenAPI, pero no ejecuta Spectral directamente. Si tiene reglas de Spectral personalizadas en las que su equipo confía, siga ejecutándolas en CI (GitHub Actions o GitLab CI) independientemente de Apidog. La cobertura de linting de Apidog y si puede compartir conjuntos de reglas de linting personalizados entre proyectos vale la pena verificarlos en una prueba contra sus requisitos específicos de reglas.

Pruebas de API: Stoplight Platform incluye pruebas de API basadas en escenarios. El ejecutor de pruebas de Apidog le permite construir escenarios de prueba visualmente, encadenar solicitudes y ejecutar aserciones contra el cuerpo de la respuesta, los encabezados y los códigos de estado. Reconstruirá estos dentro de Apidog; no hay una importación automatizada desde proyectos de prueba de Stoplight. La guía de flujo de trabajo de API nativo de Git muestra cómo integrar las ejecuciones de prueba de Apidog en una pipeline de GitHub Actions.

Un ejemplo práctico: si su prueba de Stoplight verificó que POST /orders devuelve un 201 con un encabezado location, aquí está la configuración de prueba equivalente en Apidog en una pipeline de CI usando la CLI de Apidog:

# .github/workflows/api-tests.yml
name: Pruebas de contrato de API

on:
  pull_request:
    branches: [main]

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

      - name: Ejecutar pruebas de Apidog
        run: |
          npx apidog-cli run \
            --project-id ${{ secrets.APIDOG_PROJECT_ID }} \
            --test-id ${{ secrets.APIDOG_TEST_SUITE_ID }} \
            --env production \
            --reporter junit \
            --output test-results.xml
        env:
          APIDOG_API_KEY: ${{ secrets.APIDOG_API_KEY }}

      - name: Publicar resultados de pruebas
        uses: mikepenz/action-junit-report@v4
        if: always()
        with:
          report_paths: test-results.xml

Esto reemplaza una ejecución de prueba de Stoplight en CI y mantiene intacta su estructura existente de GitHub Actions.

Lista de verificación de evaluación para equipos empresariales

Si está migrando para un equipo más grande (el tipo que evalúa Stoplight Platform en lugar de Studio), hay capacidades específicas que vale la pena verificar antes de comprometerse. Apidog cubre estas áreas, pero el comportamiento exacto depende de su plan y configuración del espacio de trabajo.

Enfóquese en estas como tareas de evaluación, no como bloqueadores. La mayoría se pueden confirmar en una prueba de dos semanas con un proyecto representativo.

Preguntas frecuentes

¿Puedo seguir usando Spectral con Apidog?

Sí. Ejecute Spectral en su pipeline de CI independientemente de Apidog. Su archivo .spectral.yaml permanece en el repositorio y su trabajo de CI (GitHub Actions, GitLab CI) aplica linting al archivo OpenAPI en cada PR. Apidog maneja la documentación, la simulación y las pruebas; Spectral maneja el linting. No entran en conflicto. Consulte la documentación de Spectral para conocer las opciones de integración de CI.

¿Se romperán mis rutas $ref cuando conecte el repositorio a Apidog?

No si sus rutas son correctas en el archivo de especificación. Apidog resuelve $ref en relación con la ubicación del archivo OpenAPI raíz. Si su especificación dice $ref: '../models/error.json' y la carpeta models/ está un nivel por encima de reference/, Apidog sigue esa ruta relativa en el repositorio. Pruebe primero con una especificación que use referencias externas.

¿El Modo Spec-First de Apidog es compatible con GitLab además de GitHub?

Sí, tanto GitHub como GitLab son compatibles. El flujo de conexión es el mismo; se autentica con su cuenta de GitLab y selecciona el repositorio y la rama. Para obtener más información sobre las opciones de control de versiones, la guía de control de versiones de OpenAPI con Git cubre las estrategias de ramas en detalle.

¿Qué sucede con la URL de mis documentos de Stoplight existentes después de la migración?

Las URLs de la documentación alojada en Stoplight (docs.stoplight.io/your-org/your-api) dejarán de funcionar una vez que cancele su suscripción a Stoplight. Apidog le da a sus documentos una nueva URL en un subdominio que usted configura. Configure redireccionamientos en la capa de DNS o CDN si tiene enlaces externos que apuntan a sus páginas de documentos de Stoplight.

¿Necesito eliminar .stoplight.json y toc.json del repositorio?

No. Apidog ignora los archivos que no reconoce. Déjelos en su lugar si eliminarlos pudiera causar conflictos de fusión o confusión. Una vez que el equipo esté completamente en Apidog, puede eliminarlos en un PR de limpieza, pero no es necesario para que la migración funcione.

Conclusión

Migrar de Stoplight a Apidog no significa empezar de cero. Sus especificaciones OpenAPI permanecen en Git, su flujo de trabajo de ramas se mantiene intacto y su estructura de directorios reference/, models/ y docs/ se mapea limpiamente a lo que Apidog espera. La migración es un intercambio de configuración: reemplace .stoplight.json y toc.json con la configuración del proyecto Apidog, conecte su repositorio a través del Modo Spec-First y reconstruya sus escenarios de prueba dentro del ejecutor de pruebas de Apidog.

Comience su migración de Stoplight conectando el Modo Spec-First de Apidog a su repositorio OpenAPI existente de GitHub o GitLab. Sin volver a cargar, sin dependencia, el mismo historial de Git. Descargue Apidog para comenzar y use un proyecto API representativo para su prueba para revisar la lista de verificación anterior con sus datos reales.