DEV Community

Cover image for Cómo migrar de Stoplight a Apidog (Flujo de trabajo Spec-First)
Roobia
Roobia

Posted on • Originally published at apidog.com

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

Si está migrando de Stoplight Studio o Stoplight Platform a Apidog, no vuelva a cargar sus especificaciones OpenAPI ni cambie su flujo de Git. El Modo Spec-First de Apidog, actualmente en beta, se conecta directamente a su repositorio de GitHub o GitLab. Git sigue siendo la fuente de la verdad, el historial de commits permanece intacto y la migración se centra en reemplazar configuración de Stoplight por configuración de Apidog.

Prueba Apidog hoy

Equipos que ya gestionan especificaciones OpenAPI en Git junto con Stoplight para documentación pueden migrar sin rediseñar su repositorio. Si aún está comparando opciones antes de decidir, revise también las principales alternativas a Stoplight Studio.

Qué permanece igual al migrar

No cambian:

  • Sus archivos OpenAPI en YAML o JSON.
  • Su repositorio Git.
  • Su estrategia de ramas.
  • Sus referencias $ref, siempre que las rutas relativas sean correctas.
  • Su historial de commits y revisiones.

Stoplight almacena las especificaciones como archivos versionados. Apidog lee esos mismos archivos cuando conecta el repositorio en Modo Spec-First.

Lo que sí cambia es la capa de herramientas:

  • Renderizado de documentación.
  • Mock server.
  • Ejecutor de pruebas.
  • Cliente API.
  • Configuración de navegación y publicación.

En lugar de usar Stoplight para documentación y otra herramienta para pruebas, Apidog centraliza documentación, mocks, pruebas y cliente API en un solo espacio de trabajo sincronizado con el archivo OpenAPI que su equipo ya mantiene en Git.

La migración, en la práctica, es un intercambio de configuración, no una migración de datos.

Paso 1: Exporte los activos de su proyecto Stoplight

Antes de configurar Apidog, confirme qué parte de su proyecto ya vive en Git y qué debe exportar manualmente.

Si usa Stoplight Studio con backend de Git

Sus especificaciones OpenAPI, modelos JSON Schema y documentación Markdown probablemente ya están confirmados en el repositorio.

Ejecute:

git pull
Enter fullscreen mode Exit fullscreen mode

Después valide la estructura. Un proyecto típico de Stoplight puede verse así:

your-api-repo/
  .stoplight.json          # Configuración del proyecto Stoplight
  reference/
    petstore.yaml          # Especificaciones OpenAPI
  models/
    error.json             # Modelos compartidos de JSON Schema
  docs/
    introduction.md        # Páginas Markdown
    authentication.md
  toc.json                 # Orden de la tabla de contenido
  assets/
    images/
      architecture.png
Enter fullscreen mode Exit fullscreen mode

Stoplight usa la Especificación OpenAPI, por lo que los archivos de especificación funcionan en Apidog sin conversión si son válidos.

Si usa Stoplight Platform sin backend de Git

Exporte manualmente cada proyecto API:

  1. Abra el proyecto en Stoplight.
  2. Vaya a Exportar.
  3. Descargue el archivo OpenAPI YAML.
  4. Copie las páginas Markdown en una carpeta docs/.
  5. Copie imágenes y activos en assets/.
  6. Cree un repositorio Git nuevo en GitHub o GitLab.
  7. Confirme los archivos exportados.

Ejemplo:

mkdir your-api-repo
cd your-api-repo

mkdir reference docs assets models

# Copie aquí sus archivos exportados
git init
git add .
git commit -m "Export Stoplight API project"
Enter fullscreen mode Exit fullscreen mode

Cuando sus archivos estén en Git, continúe con la conexión a Apidog.

Paso 2: Identifique qué configuración de Stoplight va a reemplazar

Stoplight usa principalmente dos archivos de configuración. Apidog no necesita equivalentes archivo-a-archivo, porque esa configuración se realiza desde la UI del proyecto.

Archivo o convención de Stoplight Qué hace Cómo se configura en Apidog
.stoplight.json Define raíz del proyecto, rutas de especificaciones, documentos y archivos incluidos Configuración de conexión del repositorio en el proyecto Apidog
toc.json Controla el orden y agrupación de páginas en la barra lateral Estructura de documentos y orden configurado en el editor de Docs de Apidog
reference/ Carpeta habitual para especificaciones OpenAPI Ruta configurable en Modo Spec-First
models/ JSON Schema compartidos Referencias desde components/schemas mediante $ref
docs/ Páginas de guía en Markdown Importación como páginas de documentación
assets/ Imágenes y archivos estáticos Carga en Apidog o uso de URLs públicas/CDN

Puede dejar .stoplight.json y toc.json en el repositorio durante la migración. Apidog ignora archivos desconocidos. Elimínelos solo cuando el equipo ya no dependa de Stoplight.

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

El Modo Spec-First de Apidog conecta un repositorio GitHub o GitLab a un proyecto Apidog para que la especificación OpenAPI se lea desde Git.

Flujo recomendado:

  1. Cree un proyecto nuevo en Apidog.
  2. Seleccione Modo Spec-First.
  3. Autentique Apidog con GitHub o GitLab.
  4. Seleccione el repositorio.
  5. Seleccione la rama.
  6. Indique la ruta del archivo OpenAPI.
  7. Guarde la configuración.

Si necesita revisar permisos de OAuth, consulte la documentación de GitHub sobre conexión de aplicaciones de terceros a repositorios.

Use la rama predeterminada (main o master) para especificaciones productivas. Para validar la migración sin afectar producción, cree una rama temporal:

git checkout -b migrate-stoplight-to-apidog
Enter fullscreen mode Exit fullscreen mode

Después de guardar, Apidog lee la especificación y genera:

  • Documentación interactiva.
  • Endpoints de mock.
  • Estructura base para pruebas.
  • Cliente API para ejecutar solicitudes.

Si su OpenAPI usa referencias externas, por ejemplo:

components:
  schemas:
    Error:
      $ref: '../models/error.json'
Enter fullscreen mode Exit fullscreen mode

Apidog resolverá la ruta de forma relativa al archivo OpenAPI raíz. No requiere configuración adicional si la ruta ya es válida.

Para más detalles sobre esta sincronización, revise la guía para sincronizar especificaciones OpenAPI con GitHub.

Paso 4: Migre la documentación Markdown

Stoplight permite combinar documentación Markdown con referencia API en la misma barra lateral. En Apidog puede replicar esa estructura desde la sección Docs.

Pasos:

  1. Abra el proyecto Apidog.
  2. Entre en Docs.
  3. Use Importar > Markdown.
  4. Cargue los archivos desde docs/.
  5. Revise encabezados, enlaces internos e imágenes.
  6. Reordene las páginas desde el editor de documentación.

Si sus páginas Markdown referencian imágenes locales:

![Arquitectura](../assets/images/architecture.png)
Enter fullscreen mode Exit fullscreen mode

Tiene dos opciones:

  1. Cargar las imágenes en Apidog y actualizar la ruta.
  2. Publicarlas en un CDN o URL pública y mantener referencias absolutas.

Ejemplo con URL pública:

![Arquitectura](https://cdn.example.com/api-docs/architecture.png)
Enter fullscreen mode Exit fullscreen mode

Revise especialmente:

  • Enlaces relativos entre páginas.
  • Imágenes con rutas locales.
  • Tablas Markdown.
  • Bloques de código.
  • Encabezados usados para navegación.

Paso 5: Reemplace el mock server de Stoplight

Stoplight Studio puede ejecutar un mock server local desde la especificación OpenAPI. Apidog también genera mocks desde OpenAPI, pero los expone como URLs compartidas para el equipo.

Si antes ejecutaba algo como:

stoplight mock reference/your-api.yaml
Enter fullscreen mode Exit fullscreen mode

En Apidog el flujo cambia a:

  1. Conectar la especificación en Modo Spec-First.
  2. Abrir la operación en Apidog.
  3. Revisar el mock generado.
  4. Compartir la URL del mock con frontend, QA o integraciones internas.

Apidog genera respuestas mock a partir de:

  • examples
  • example
  • Esquemas definidos en responses
  • Motor de mock inteligente si no hay ejemplos explícitos

Ejemplo OpenAPI con examples:

paths:
  /orders:
    post:
      responses:
        '201':
          description: Orden creada
          headers:
            location:
              schema:
                type: string
          content:
            application/json:
              examples:
                created:
                  value:
                    id: "ord_123"
                    status: "created"
Enter fullscreen mode Exit fullscreen mode

Antes de reemplazar el mock local, valide:

  • Que la URL cloud sea accesible desde su red.
  • Que las respuestas coincidan con los ejemplos esperados.
  • Que las políticas internas permitan mocks alojados.
  • Que los entornos frontend puedan consumir la nueva URL.

Paso 6: Reconstruya sus conjuntos de pruebas

Si usaba pruebas de contrato de Stoplight o reglas de Spectral, trátelas por separado.

Mantenga Spectral en CI

Stoplight usa Spectral para linting de OpenAPI mediante .spectral.yaml.

Apidog tiene reglas de linting propias para cumplimiento OpenAPI, pero no ejecuta Spectral directamente. Si su equipo depende de reglas personalizadas, mantenga Spectral en CI.

Ejemplo con GitHub Actions:

# .github/workflows/openapi-lint.yml
name: Lint OpenAPI

on:
  pull_request:
    branches: [main]

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

      - name: Instalar Spectral
        run: npm install -g @stoplight/spectral-cli

      - name: Ejecutar linting
        run: spectral lint reference/your-api.yaml
Enter fullscreen mode Exit fullscreen mode

Así conserva las mismas reglas de validación mientras Apidog gestiona documentación, mocks y pruebas.

Reconstruya pruebas API en Apidog

Stoplight Platform incluye pruebas basadas en escenarios. En Apidog debe reconstruirlas dentro del ejecutor de pruebas. No hay importación automatizada desde proyectos de prueba de Stoplight.

En Apidog puede crear escenarios para:

  • Encadenar solicitudes.
  • Validar códigos de estado.
  • Validar headers.
  • Validar cuerpo JSON.
  • Extraer variables de una respuesta y usarlas en la siguiente.
  • Ejecutar pruebas en CI.

La guía de flujo de trabajo de API nativo de Git muestra cómo integrar pruebas de Apidog en GitHub Actions.

Ejemplo: si su prueba de Stoplight validaba que POST /orders devuelve 201 y un header location, cree el escenario equivalente en Apidog y ejecútelo en CI con la CLI:

# .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
Enter fullscreen mode Exit fullscreen mode

Esto mantiene su estructura de GitHub Actions y reemplaza la ejecución de pruebas de Stoplight por una ejecución de Apidog.

Lista de verificación para equipos empresariales

Si migra un equipo grande, valide estas capacidades con un proyecto representativo antes de completar el cambio.

Capacidad Qué verificar en Apidog
Acceso a documentación privada Confirme si puede restringir páginas a usuarios autenticados o dominios específicos.
Reutilización de esquemas Pruebe si puede reutilizar components/schemas entre proyectos sin duplicar archivos.
Reglas de linting personalizadas Verifique si necesita mantener Spectral en CI o si las reglas de Apidog cubren sus requisitos.
SSO/SCIM Confirme compatibilidad con su proveedor de identidad y granularidad de aprovisionamiento.
Registros de auditoría Revise qué eventos se capturan y si cumplen sus requisitos de seguridad.
Acceso a mocks Valide que las URLs de mock sean accesibles desde sus redes y entornos.
Estrategia de ramas Pruebe cómo se comportan main, ramas de feature y PRs con el flujo Spec-First.
Referencias externas Valide $ref hacia models/, archivos compartidos y rutas relativas.

Trate esta lista como una prueba de aceptación. Una evaluación de dos semanas con una API real suele ser suficiente para detectar ajustes de configuración.

Preguntas frecuentes

¿Puedo seguir usando Spectral con Apidog?

Sí. Ejecute Spectral en su pipeline de CI de forma independiente. Su archivo .spectral.yaml permanece en el repositorio y GitHub Actions o GitLab CI aplican linting en cada PR. Apidog gestiona documentación, mocks y pruebas; Spectral gestiona linting. No entran en conflicto.

Consulte la documentación de Spectral para opciones de integración en CI.

¿Se romperán mis rutas $ref al conectar el repositorio a Apidog?

No, si las rutas son correctas en el archivo OpenAPI.

Ejemplo:

components:
  schemas:
    Error:
      $ref: '../models/error.json'
Enter fullscreen mode Exit fullscreen mode

Si models/ está un nivel por encima de reference/, Apidog seguirá esa ruta relativa. Antes de migrar todo el proyecto, pruebe con una especificación que use referencias externas.

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

Sí. GitHub y GitLab son compatibles. El flujo es similar: autenticarse, seleccionar repositorio, elegir rama y configurar la ruta del archivo OpenAPI.

Para estrategias de ramas y control de versiones, revise la guía de control de versiones de OpenAPI con Git.

¿Qué sucede con la URL de mi documentación de Stoplight?

Las URLs alojadas en Stoplight, como:

docs.stoplight.io/your-org/your-api
Enter fullscreen mode Exit fullscreen mode

dejarán de funcionar si cancela Stoplight. Apidog publicará la documentación en una nueva URL o subdominio configurado.

Si tiene enlaces externos, configure redirecciones en DNS, CDN o proxy antes de apagar Stoplight.

¿Debo eliminar .stoplight.json y toc.json?

No es obligatorio. Apidog los ignora.

Recomendación práctica:

  1. Déjelos durante la migración.
  2. Termine la validación en Apidog.
  3. Avise al equipo.
  4. Elimínelos en un PR de limpieza cuando ya no haya dependencia de Stoplight.

Ejemplo:

git rm .stoplight.json toc.json
git commit -m "Remove Stoplight configuration"
Enter fullscreen mode Exit fullscreen mode

Conclusión

Migrar de Stoplight a Apidog no requiere empezar desde cero. Sus especificaciones OpenAPI permanecen en Git, su historial se conserva y sus carpetas reference/, models/ y docs/ pueden mapearse al flujo de Apidog.

El plan recomendado es:

  1. Exporte o confirme todos los activos en Git.
  2. Identifique qué configuración de Stoplight será reemplazada.
  3. Conecte el repositorio con el Modo Spec-First de Apidog.
  4. Importe documentación Markdown.
  5. Valide mocks.
  6. Reconstruya pruebas API.
  7. Mantenga Spectral en CI si usa reglas personalizadas.
  8. Ejecute una prueba con una API representativa antes de desactivar Stoplight.

Comience conectando el Modo Spec-First de Apidog a su repositorio OpenAPI existente de GitHub o GitLab. Sin volver a cargar archivos, sin perder historial de Git y sin cambiar la fuente de verdad. Descargue Apidog y use un proyecto API real para validar la lista de verificación anterior.

Top comments (0)