DEV Community

Cover image for Comment migrer de Stoplight vers Apidog (Workflow axé sur les spécifications)
Antoine Laurent
Antoine Laurent

Posted on • Originally published at apidog.com

Comment migrer de Stoplight vers Apidog (Workflow axé sur les spécifications)

Si vous migrez de Stoplight Studio ou Stoplight Platform vers Apidog, vous n’avez pas besoin de réimporter vos spécifications OpenAPI. Le Mode Spec-First d’Apidog, actuellement en bêta, se connecte directement à votre dépôt GitHub ou GitLab existant. Git reste donc la source de vérité, et votre historique de commits reste intact. Ce guide montre comment exporter ce qui doit l’être depuis Stoplight, faire correspondre votre structure de dépôt aux attentes d’Apidog, puis remplacer .stoplight.json et toc.json par la configuration Apidog équivalente.

Essayez Apidog aujourd’hui

Si votre équipe gère déjà ses spécifications OpenAPI dans Git et utilise Stoplight pour la documentation, la migration est surtout un changement de configuration. Si vous comparez encore les options, consultez aussi l’article sur les meilleures alternatives à Stoplight Studio.

Ce qui ne change pas pendant la migration

Vos fichiers OpenAPI, votre dépôt Git et votre stratégie de branches ne changent pas.

Stoplight stocke généralement les spécifications sous forme de fichiers YAML ou JSON versionnés. Apidog lit ces mêmes fichiers lorsque vous connectez un dépôt en Mode Spec-First.

Ce qui change :

  • le moteur de rendu de documentation ;
  • le serveur de mock ;
  • l’exécuteur de tests ;
  • le client API ;
  • la configuration projet spécifique à Stoplight.

Au lieu d’utiliser Stoplight pour la documentation et un autre outil comme Postman pour les tests, Apidog regroupe documentation, mocks, tests et client API dans un même espace de travail synchronisé avec votre fichier OpenAPI.

En pratique, la migration consiste surtout à remplacer des fichiers de configuration Stoplight par des paramètres Apidog.

Étape 1 : exporter les ressources Stoplight

Avant de configurer Apidog, identifiez ce qui existe déjà dans Git et ce qui doit être exporté.

Cas 1 : Stoplight Studio avec backend Git

Si Stoplight Studio est connecté à Git, vos spécifications OpenAPI, modèles JSON Schema et pages Markdown sont déjà dans le dépôt.

Commencez par synchroniser votre clone local :

git pull
Enter fullscreen mode Exit fullscreen mode

Votre dépôt ressemble souvent à ceci :

your-api-repo/
  .stoplight.json          # Configuration Stoplight à remplacer
  reference/
    petstore.yaml          # Spécification(s) OpenAPI
  models/
    error.json             # Modèles JSON Schema partagés
  docs/
    introduction.md        # Pages de guide Markdown
    authentication.md
  toc.json                 # Ordre de la table des matières Stoplight
  assets/
    images/
      architecture.png
Enter fullscreen mode Exit fullscreen mode

Les fichiers OpenAPI respectant la Spécification OpenAPI peuvent être lus par Apidog sans conversion.

Cas 2 : Stoplight Platform sans backend Git

Si vos projets sont hébergés dans Stoplight Platform sans dépôt Git :

  1. Ouvrez chaque projet API dans Stoplight.
  2. Exportez la spécification OpenAPI au format YAML ou JSON.
  3. Copiez les pages Markdown dans un dossier docs/.
  4. Placez les fichiers dans un nouveau dépôt GitHub ou GitLab.

Exemple de structure cible :

your-api-repo/
  reference/
    openapi.yaml
  docs/
    introduction.md
    authentication.md
  assets/
    images/
Enter fullscreen mode Exit fullscreen mode

Une fois le dépôt prêt, passez à la configuration Apidog.

Étape 2 : identifier les fichiers Stoplight à remplacer

Stoplight utilise principalement deux fichiers propriétaires pour piloter la structure du projet.

Fichier ou convention Stoplight Rôle Équivalent dans Apidog
.stoplight.json Déclare la racine du projet, les chemins des spécifications, les chemins des documents et les fichiers inclus Paramètres de connexion du dépôt dans le projet Apidog, configurés via l’interface
toc.json Contrôle l’ordre et le regroupement des pages dans la barre latérale Stoplight Structure et ordre définis dans l’éditeur de documentation Apidog
reference/ Emplacement habituel des fichiers OpenAPI Chemin configurable dans le Mode Spec-First
models/ Fichiers JSON Schema réutilisés Références via components/schemas et $ref dans OpenAPI
docs/ Pages Markdown Pages importées dans la documentation Apidog

Vous pouvez laisser .stoplight.json et toc.json dans le dépôt pendant la migration. Apidog ignore les fichiers qu’il ne reconnaît pas.

Supprimez-les uniquement lorsque l’équipe n’utilise plus Stoplight.

Étape 3 : connecter le dépôt au Mode Spec-First d’Apidog

Le Mode Spec-First d’Apidog permet de lier un dépôt GitHub ou GitLab à un projet Apidog. La spécification OpenAPI reste lue depuis Git, pas depuis une base interne.

Cela permet de conserver le workflow existant :

developer opens PR
        ↓
OpenAPI file updated
        ↓
CI validates spec
        ↓
Apidog reads latest spec from Git
        ↓
documentation, mocks and tests stay aligned
Enter fullscreen mode Exit fullscreen mode

Connexion du dépôt

  1. Dans Apidog, créez un nouveau projet en Mode Spec-First.
  2. Authentifiez Apidog avec GitHub ou GitLab.
  3. Sélectionnez le dépôt contenant votre spécification OpenAPI.

  1. Sélectionnez la branche à utiliser :
    • main ou master pour la documentation de production ;
    • une branche de test pour valider la migration avant bascule.

  1. Indiquez le chemin du fichier OpenAPI, par exemple : 
reference/petstore.yaml
Enter fullscreen mode Exit fullscreen mode
  1. Enregistrez le projet.

Apidog lit alors la spécification et génère :

  • la documentation interactive ;
  • les endpoints de mock ;
  • la base des tests API ;
  • les collections de requêtes utilisables dans le client API.

Si votre spécification utilise des références externes comme ceci :

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

Apidog résout les chemins relativement à l’emplacement du fichier OpenAPI racine.

Pour approfondir la synchronisation avec GitHub, consultez le guide de synchronisation OpenAPI vers GitHub.

Étape 4 : migrer la documentation Markdown

Stoplight permet de combiner référence API et guides Markdown dans une même documentation. Apidog le permet aussi via son éditeur de documentation.

Pour importer vos pages :

  1. Ouvrez le projet Apidog.
  2. Allez dans Docs.
  3. Utilisez Importer > Markdown.
  4. Importez les fichiers depuis votre dossier docs/, ou collez le contenu page par page.
  5. Réorganisez les pages dans la barre latérale Apidog.

Si vos fichiers Markdown contiennent des images locales :

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

vous avez deux options :

  • importer les images dans le stockage de fichiers Apidog, puis mettre à jour les chemins ;
  • conserver les URLs existantes si les images sont déjà hébergées sur un CDN ou une URL publique.

Exemple avec une URL publique :

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

Étape 5 : remplacer le serveur de mock Stoplight

Stoplight Studio propose un serveur de mock local qui lit votre fichier OpenAPI.

Exemple côté Stoplight :

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

Avec Apidog, les mocks sont générés à partir de la spécification connectée en Mode Spec-First. Ils sont accessibles via une URL cloud partagée, ce qui évite à chaque développeur ou QA de lancer un serveur local.

Après connexion du dépôt, Apidog crée des endpoints de mock pour les opérations définies dans OpenAPI.

Exemple d’opération :

paths:
  /orders:
    post:
      summary: Create an order
      responses:
        "201":
          description: Order created
          headers:
            location:
              schema:
                type: string
          content:
            application/json:
              examples:
                created:
                  value:
                    id: "ord_123"
                    status: "created"
Enter fullscreen mode Exit fullscreen mode

Apidog utilise les exemples définis dans examples. Si aucun exemple n’est présent, le moteur de mock intelligent peut générer une réponse à partir du schéma.

À valider pendant l’essai :

  • les URLs de mock sont accessibles depuis votre réseau ;
  • les règles d’accès correspondent à vos politiques internes ;
  • les réponses générées correspondent aux cas utilisés par le frontend et la QA ;
  • les overrides de réponse par endpoint couvrent vos scénarios de test.

Étape 6 : reconstruire les tests API

Les tests Stoplight ne sont pas importés automatiquement dans Apidog. Vous devez les recréer dans l’exécuteur de tests Apidog.

Si vous utilisez Spectral

Stoplight utilise Spectral pour le linting OpenAPI, souvent via un fichier :

.spectral.yaml
Enter fullscreen mode Exit fullscreen mode

Apidog dispose de règles de linting intégrées pour OpenAPI, mais n’exécute pas directement Spectral.

Si votre équipe dépend de règles Spectral personnalisées, conservez-les dans votre pipeline CI.

Exemple GitHub Actions :

name: OpenAPI lint

on:
  pull_request:
    branches: [main]

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

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

      - name: Lint OpenAPI
        run: spectral lint reference/openapi.yaml
Enter fullscreen mode Exit fullscreen mode

Apidog peut alors gérer documentation, mocks et tests, tandis que Spectral reste dédié au linting CI.

Recréer un test API dans Apidog

Exemple de test à migrer :

POST /orders doit retourner 201 et un header location.

Dans Apidog, créez un scénario de test avec :

  1. une requête POST /orders ;
  2. une assertion sur le code HTTP ;
  3. une assertion sur la présence du header location.

Assertions attendues :

status code == 201
header location exists
Enter fullscreen mode Exit fullscreen mode

Vous pouvez ensuite exécuter ces tests dans CI avec l’interface de ligne de commande Apidog.

Exemple GitHub Actions :

# .github/workflows/api-tests.yml
name: API contract tests

on:
  pull_request:
    branches: [main]

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

      - name: Run Apidog tests
        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: Publish test results
        uses: mikepenz/action-junit-report@v4
        if: always()
        with:
          report_paths: test-results.xml
Enter fullscreen mode Exit fullscreen mode

Cette approche conserve votre structure GitHub Actions existante tout en remplaçant l’exécution de tests Stoplight.

Le guide du workflow API natif Git montre comment intégrer les tests Apidog dans un pipeline GitHub Actions.

Checklist de migration

Utilisez cette liste pour valider la migration sur un projet représentatif avant de basculer toute l’équipe.

[ ] Le dépôt GitHub ou GitLab contient la spécification OpenAPI
[ ] La branche cible est définie dans Apidog
[ ] Le chemin du fichier OpenAPI est configuré
[ ] Les références $ref externes sont résolues
[ ] Les pages Markdown principales sont importées
[ ] Les images de documentation sont accessibles
[ ] Les endpoints de mock répondent correctement
[ ] Les tests critiques sont reconstruits dans Apidog
[ ] Spectral reste exécuté en CI si nécessaire
[ ] Les URLs de documentation publiques ou privées sont validées
[ ] Les redirections depuis l’ancienne documentation Stoplight sont planifiées
Enter fullscreen mode Exit fullscreen mode

Points à vérifier pour une équipe entreprise

Si vous migrez depuis Stoplight Platform pour une grande équipe, validez aussi ces capacités pendant l’essai.

Capacité Ce qu’il faut vérifier
Documentation privée Pouvez-vous restreindre l’accès aux utilisateurs authentifiés ou à certains domaines d’e-mail ?
Réutilisation des schémas Vos components/schemas partagés peuvent-ils être référencés sans duplication entre projets ?
Règles de linting Les règles intégrées d’Apidog couvrent-elles vos besoins, ou devez-vous conserver Spectral en CI ?
SSO / SCIM Le fournisseur d’identité de votre organisation est-il pris en charge ?
Journaux d’audit Les événements enregistrés répondent-ils à vos exigences de conformité ?
Accès réseau aux mocks Les URLs cloud de mock sont-elles compatibles avec vos politiques réseau ?

Traitez ces éléments comme des vérifications d’évaluation, pas comme des prérequis bloquants. La plupart peuvent être testés en une ou deux semaines sur une API réelle.

FAQ

Puis-je continuer à utiliser Spectral avec Apidog ?

Oui. Conservez .spectral.yaml dans le dépôt et exécutez Spectral dans votre pipeline CI, indépendamment d’Apidog.

Apidog gère la documentation, les mocks et les tests. Spectral reste responsable du linting OpenAPI. Les deux ne sont pas en conflit.

Consultez la documentation Spectral pour les options d’intégration CI.

Mes chemins $ref seront-ils cassés après la connexion du dépôt ?

Non, si les chemins sont corrects dans votre fichier OpenAPI.

Apidog résout les références relativement à l’emplacement du fichier OpenAPI racine.

Exemple :

$ref: ../models/error.json
Enter fullscreen mode Exit fullscreen mode

Si models/ se trouve bien un niveau au-dessus du dossier reference/, la référence sera résolue.

Testez d’abord avec une spécification contenant des références externes avant de migrer toute l’équipe.

Le Mode Spec-First d’Apidog prend-il en charge GitLab ?

Oui. GitHub et GitLab sont pris en charge.

Le processus est similaire :

  1. authentification avec le compte GitLab ;
  2. sélection du dépôt ;
  3. sélection de la branche ;
  4. configuration du chemin vers le fichier OpenAPI.

Pour les stratégies de branches, consultez le guide du contrôle de version OpenAPI avec Git.

Que devient mon ancienne URL de documentation Stoplight ?

Les URLs hébergées par Stoplight, par exemple :

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

cessent de fonctionner lorsque vous arrêtez votre abonnement Stoplight.

Apidog attribue une nouvelle URL à votre documentation. Si des liens externes pointent vers votre ancienne documentation, configurez des redirections côté DNS, reverse proxy ou CDN.

Dois-je supprimer .stoplight.json et toc.json ?

Non. Apidog ignore ces fichiers.

Vous pouvez les laisser pendant la période de transition pour éviter les conflits de merge ou la confusion. Une fois Stoplight complètement retiré du workflow, supprimez-les dans une PR de nettoyage.

Conclusion

Migrer de Stoplight vers Apidog ne nécessite pas de reconstruire votre API depuis zéro. Vos spécifications OpenAPI restent dans Git, vos branches restent intactes, et vos dossiers reference/, models/ et docs/ peuvent être réutilisés.

La migration consiste principalement à :

  1. exporter les fichiers manquants depuis Stoplight ;
  2. connecter le dépôt GitHub ou GitLab au Mode Spec-First d’Apidog ;
  3. importer les pages Markdown ;
  4. remplacer le mock local Stoplight par les mocks Apidog ;
  5. reconstruire les tests critiques dans Apidog ;
  6. conserver Spectral en CI si vous avez des règles personnalisées.

Commencez avec un projet API représentatif, validez les références $ref, les mocks, les tests et les règles d’accès, puis basculez progressivement le reste de l’équipe. Vous pouvez aussi télécharger Apidog pour lancer l’essai avec votre dépôt OpenAPI existant.

Top comments (0)