Si vous passez de Stoplight Studio ou Stoplight Platform à Apidog, la première chose à savoir est que vous n'avez pas besoin de re-télécharger vos spécifications OpenAPI. Le Mode Spec-First d'Apidog (actuellement en version bêta) se connecte directement à votre dépôt GitHub ou GitLab existant, de sorte que Git reste la source de vérité et que votre historique de commits reste intact. Ce guide détaille chaque étape : l'exportation de votre configuration Stoplight, la correspondance de ses conventions de répertoires avec les attentes d'Apidog, et le remplacement de .stoplight.json et toc.json par leurs équivalents Apidog.
Des équipes comme celles du Forum Économique Mondial gèrent déjà leurs spécifications OpenAPI dans Git aux côtés de Stoplight pour la documentation. Si cela décrit votre configuration, ce guide est fait pour vous. Et si vous êtes encore en train d'évaluer les options plutôt que de vous engager dans une migration, l'article sur les meilleures alternatives à Stoplight Studio couvre le paysage plus large.
Ce qui reste inchangé lors de la migration
Vos fichiers OpenAPI, votre dépôt Git et votre stratégie de branche ne changent pas. C'est la prémisse clé. Stoplight stocke les spécifications sous forme de fichiers YAML ou JSON contrôlés par version. Apidog lit ces mêmes fichiers lorsque vous connectez un dépôt en Mode Spec-First.
Ce qui change, c'est tout ce qui est superposé : le moteur de rendu de documentation, le serveur de maquette, l'exécuteur de tests et le client API. Au lieu que Stoplight Platform serve la documentation et que Postman gère les tests comme un outil distinct, Apidog combine tout cela dans un seul espace de travail, synchronisé avec le même fichier OpenAPI que vos ingénieurs sont déjà en train de committer.
Le résultat pratique : votre migration est principalement un échange de configuration, pas une migration de données.
Étape 1 : Exporter les ressources de votre projet Stoplight
Avant de toucher à Apidog, capturez tout ce que Stoplight contient et qui n'est pas déjà dans Git.
Si vous utilisez Stoplight Studio avec un backend Git :
Vos spécifications OpenAPI, vos modèles de schéma JSON et votre documentation Markdown sont déjà committés. Effectuez un git pull pour vous assurer que votre clone local est à jour. Stoplight suit le format de la Spécification OpenAPI, et ces fichiers de spécification fonctionnent dans Apidog sans conversion. La structure de votre dépôt ressemble probablement à ceci :
your-api-repo/
.stoplight.json # Project config (needs replacement)
reference/
petstore.yaml # Your OpenAPI spec(s)
models/
error.json # Shared JSON Schema models
docs/
introduction.md # Markdown guide pages
authentication.md
toc.json # Table-of-contents order (needs replacement)
assets/
images/
architecture.png
Si vous utilisez Stoplight Platform (hébergé dans le cloud, sans backend Git) :
Exportez vos spécifications depuis l'interface utilisateur de Stoplight : ouvrez chaque projet API, allez dans « Exporter », et téléchargez le fichier YAML OpenAPI. Pour les documents Markdown, copiez-les dans un dossier docs/ dans un nouveau dépôt Git. Stoplight n'offre pas d'exportation en masse pour les projets non-Git, donc faites cela par projet API.
Une fois vos fichiers dans un dépôt Git (GitHub ou GitLab), passez à l'étape suivante.
Étape 2 : Comprendre les fichiers de configuration que vous remplacez
Deux fichiers spécifiques à Stoplight pilotent la structure du projet. Aucun n'a d'équivalent direct dans Apidog, mais comprendre leur fonction vous indique exactement ce qu'il faut configurer dans Apidog à la place.
| Fichier Stoplight | Ce qu'il fait | Équivalent Apidog |
|---|---|---|
.stoplight.json |
Déclare la racine du projet, les chemins des spécifications, les chemins des documents et les fichiers inclus dans le projet | Paramètres de connexion du dépôt au sein du projet Apidog (configurés via l'interface utilisateur, pas un fichier) |
toc.json |
Contrôle l'ordre et le regroupement des pages dans la barre latérale des documents Stoplight | Apidog lit la structure des répertoires ; l'ordre de la barre latérale est défini dans l'éditeur de documents Apidog, et non dans un fichier plat |
convention reference/ |
Là où Stoplight attend les fichiers de spécification OpenAPI | Configurable en Mode Spec-First d'Apidog ; par défaut, il pointe vers la racine du dépôt, mais vous pouvez le diriger vers reference/ |
convention models/ |
Fichiers de schéma JSON pour les composants partagés | Référencez-les depuis la section components/schemas de votre spécification OpenAPI ; Apidog résout les chemins $ref |
convention docs/ |
Pages de guide Markdown | Importer comme pages de documentation dans Apidog ; la hiérarchie des répertoires correspond aux sections de la barre latérale |
L'idée clé : .stoplight.json et toc.json sont propriétaires à Stoplight. Vous pouvez les laisser dans le dépôt (Apidog ignore les fichiers inconnus), mais ils ne piloteront rien dans Apidog. Vous configurez les paramètres équivalents via l'interface utilisateur du projet Apidog.
Étape 3 : Connecter votre dépôt au Mode Spec-First d'Apidog
Le Mode Spec-First d'Apidog est la façon de lier un dépôt GitHub ou GitLab à un projet Apidog afin que la spécification OpenAPI soit toujours lue depuis Git, et non depuis une base de données interne d'Apidog. Cela maintient Git comme source faisant autorité, et cela signifie que vos ingénieurs peuvent continuer à soumettre des PR pour mettre à jour la spécification exactement comme ils le font aujourd'hui.
Voici le processus de connexion. Vous pouvez également consulter la documentation de GitHub sur la connexion d'applications tierces aux dépôts si vous avez des doutes concernant l'octroi des autorisations OAuth.
- Dans Apidog, créez un nouveau projet en Mode Spec-First
- Authentifiez Apidog avec votre compte GitHub ou GitLab et sélectionnez le dépôt.
3.Définissez la branche : utilisez votre branche par défaut (main ou master) pour les spécifications de production, ou une branche de fonctionnalité pendant les tests de migration.
- Enregistrez. Apidog lit la spécification et en construit la documentation interactive, les points d'accès du serveur de maquette et l'échafaudage de test.
Si votre spécification utilise $ref pour importer des schémas depuis le répertoire models/, Apidog résout ces références par rapport à l'emplacement du fichier de spécification. Aucune configuration supplémentaire n'est nécessaire tant que les chemins dans votre fichier OpenAPI sont corrects. Pour un aperçu plus approfondi du fonctionnement de cette synchronisation Git, le guide de synchronisation de la spécification OpenAPI vers GitHub couvre les mécanismes en détail.
Étape 4 : Migrer votre documentation Markdown
Stoplight vous permet de mélanger les pages de guide Markdown avec les documents de référence API dans une seule barre latérale. Apidog fait de même via son éditeur de documentation.
Après avoir connecté votre dépôt, importez vos fichiers Markdown docs/ :
- Dans le projet Apidog, ouvrez la section Docs.
- Utilisez Importer > Markdown et téléchargez vos fichiers, ou collez le contenu page par page.
Pour les ressources d'image référencées dans votre Markdown (le dossier assets/images/ dans une disposition Stoplight typique), téléchargez-les vers le stockage de fichiers d'Apidog et mettez à jour les références  dans chaque page. Si vos images sont déjà hébergées sur un CDN ou une URL publique, vous n'avez rien à changer.
Étape 5 : Remplacer le serveur de maquette de Stoplight
Stoplight Studio inclut un serveur de maquette local qui lit votre spécification OpenAPI et renvoie des exemples de réponses. Le serveur de maquette d'Apidog fait de même, mais il est hébergé dans le cloud et accessible à toute votre équipe sans exécuter de processus local.
Une fois votre spécification connectée via le Mode Spec-First, Apidog génère automatiquement des points d'accès de maquette pour chaque opération définie dans votre fichier OpenAPI. Les exemples de réponses proviennent du champ examples de votre spécification, ou du moteur de maquette intelligent d'Apidog si aucun exemple n'est défini. Vous pouvez annuler les règles de réponse par point d'accès dans Apidog sans toucher au fichier de spécification.
Pour une équipe habituée à exécuter stoplight mock reference/your-api.yaml localement, le changement est que vos ingénieurs QA et développeurs frontend accèdent désormais à une URL cloud partagée. Cela vaut la peine d'être validé lors d'un essai pour confirmer qu'il correspond à vos politiques d'accès réseau.
Étape 6 : Reconstruire vos suites de tests
Si vous avez utilisé les tests de contrat de Stoplight ou les règles Spectral pour le linting, ceux-ci nécessitent un traitement séparé.
Règles de linting Spectral : Stoplight utilise Spectral pour le linting OpenAPI, configuré via un fichier .spectral.yaml. Apidog dispose de ses propres règles de linting intégrées pour la conformité OpenAPI, mais il n'exécute pas Spectral directement. Si vous avez des règles Spectral personnalisées sur lesquelles votre équipe compte, continuez à les exécuter en CI (GitHub Actions ou GitLab CI) indépendamment d'Apidog. La couverture de linting d'Apidog et la possibilité de partager des ensembles de règles de linting personnalisés entre les projets méritent d'être vérifiées lors d'un essai par rapport à vos exigences spécifiques en matière de règles.
Tests API : Stoplight Platform inclut des tests API basés sur des scénarios. L'exécuteur de tests d'Apidog vous permet de construire visuellement des scénarios de test, d'enchaîner les requêtes et d'exécuter des assertions sur le corps de la réponse, les en-têtes et les codes de statut. Vous les reconstruirez dans Apidog ; il n'y a pas d'importation automatisée depuis les projets de test Stoplight. Le guide du workflow API natif Git montre comment intégrer les exécutions de tests Apidog dans un pipeline GitHub Actions.
Un exemple concret : si votre test Stoplight a vérifié qu'un POST /orders renvoie un 201 avec un en-tête location, voici la configuration de test Apidog équivalente dans un pipeline CI utilisant l'interface de ligne de commande Apidog :
# .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
Cela remplace une exécution de test Stoplight en CI et maintient intacte votre structure GitHub Actions existante.
Liste de contrôle d'évaluation pour les équipes d'entreprise
Si vous migrez pour une équipe plus grande (le type qui évalue Stoplight Platform plutôt que Studio), il y a des capacités spécifiques qui méritent d'être vérifiées avant de s'engager. Apidog couvre ces domaines, mais le comportement exact dépend de votre plan et de la configuration de votre espace de travail.
| Capacité | Ce qu'il faut vérifier lors d'un essai Apidog |
|---|---|
| Accès à la documentation privée | Pouvez-vous restreindre les pages de documentation aux utilisateurs authentifiés ou à des domaines de messagerie spécifiques ? Vérifiez par rapport à vos exigences de contrôle d'accès. |
| Réutilisation de schémas/composants entre projets | Une bibliothèque partagée components/schemas peut-elle être référencée depuis plusieurs projets Apidog sans copier-coller ? Cela vaut la peine de tester avec vos fichiers de schéma réels. |
| Partage de règles de linting personnalisées | Pouvez-vous distribuer un profil de linting partagé (équivalent à un .spectral.yaml partagé) entre plusieurs projets Apidog dans le même espace de travail ? |
| Provisionnement SSO/SCIM | Le SSO d'Apidog prend-il en charge votre fournisseur d'identité ? Confirmez que la granularité du provisionnement SCIM correspond à votre processus de gestion du cycle de vie des utilisateurs. |
| Journaux d'audit | Quels événements le journal d'audit capture-t-il, et dans quel format ? Vérifiez qu'il répond à vos exigences de conformité ou de révision de sécurité. |
Considérez-les comme des tâches d'évaluation, non comme des bloqueurs. La plupart peuvent être confirmées lors d'un essai de deux semaines avec un projet représentatif.
FAQ
Puis-je continuer à utiliser Spectral avec Apidog ?
Oui. Exécutez Spectral dans votre pipeline CI indépendamment d'Apidog. Votre fichier .spectral.yaml reste dans le dépôt, et votre tâche CI (GitHub Actions, GitLab CI) effectue le linting du fichier OpenAPI à chaque PR. Apidog gère la documentation, les maquettes et les tests ; Spectral gère le linting. Ils ne sont pas en conflit. Consultez la documentation de Spectral pour les options d'intégration CI.
Mes chemins $ref seront-ils rompus lorsque je connecterai le dépôt à Apidog ?
Non, si vos chemins sont corrects dans le fichier de spécification. Apidog résout $ref par rapport à l'emplacement du fichier OpenAPI racine. Si votre spécification indique $ref: '../models/error.json' et que le dossier models/ se trouve un niveau au-dessus de reference/, Apidog suit ce chemin relatif dans le dépôt. Testez d'abord avec une spécification qui utilise des références externes.
Le Mode Spec-First d'Apidog prend-il en charge GitLab ainsi que GitHub ?
Oui, GitHub et GitLab sont tous deux pris en charge. Le processus de connexion est le même ; vous vous authentifiez avec votre compte GitLab et sélectionnez le dépôt et la branche. Pour en savoir plus sur les options de contrôle de version, le guide de contrôle de version OpenAPI avec Git couvre les stratégies de branche en détail.
Qu'advient-il de mon URL de documentation Stoplight existante après la migration ?
Les URL de documentation hébergées par Stoplight (docs.stoplight.io/your-org/your-api) cessent de fonctionner une fois que vous annulez votre abonnement Stoplight. Apidog attribue à votre documentation une nouvelle URL sur un sous-domaine que vous configurez. Configurez des redirections au niveau DNS ou CDN si vous avez des liens externes pointant vers vos pages de documentation Stoplight.
Dois-je supprimer .stoplight.json et toc.json du dépôt ?
Non. Apidog ignore les fichiers qu'il ne reconnaît pas. Laissez-les en place si leur suppression devait entraîner des conflits de fusion ou de la confusion. Une fois l'équipe entièrement passée à Apidog, vous pourrez les supprimer dans une PR de nettoyage, mais ce n'est pas une exigence pour que la migration fonctionne.
Conclusion
Migrer de Stoplight vers Apidog ne signifie pas partir de zéro. Vos spécifications OpenAPI restent dans Git, votre flux de travail de branche reste intact, et la structure de vos répertoires reference/, models/ et docs/ correspond clairement à ce qu'Apidog attend. La migration est un échange de configuration : remplacez .stoplight.json et toc.json par les paramètres du projet Apidog, connectez votre dépôt via le Mode Spec-First, et reconstruisez vos scénarios de test dans l'exécuteur de tests d'Apidog.
Commencez votre migration Stoplight en connectant le Mode Spec-First d'Apidog à votre dépôt OpenAPI GitHub ou GitLab existant. Pas de re-téléchargement, pas de verrouillage, le même historique Git. Téléchargez Apidog pour commencer, et utilisez un projet API représentatif pour votre essai afin de parcourir la liste de contrôle d'évaluation ci-dessus avec vos données réelles.