Comment migrer de Redocly vers Apidog sans perdre votre workflow Docs-as-Code

Si vous hébergez votre portail développeurs sur Redocly, vous travaillez déjà comme la plupart des équipes API le souhaitent : openapi.yaml vit dans Git, les guides sont en Markdown, et un push met à jour la documentation. La crainte lorsqu'on change d'outil, c'est de perdre cette boucle et de finir par modifier la documentation à la main dans une interface web.

Ce n'est pas une fatalité. Le Apidog Spec-first Mode conserve votre spec et votre Markdown dans le même dépôt, synchronise à chaque push via un webhook, et publie un portail avec les guides et une référence API dans une seule barre latérale. Ce guide détaille la migration, y compris la partie qui ne se reporte pas automatiquement : le contenu long que de nombreux utilisateurs de Redocly conservent dans info.description et tags[].description.

Si vous êtes encore en train de comparer les outils, commencez par Apidog vs. Redocly ou la liste plus large des alternatives à Redocly. Cet article suppose que vous avez choisi Apidog et que vous voulez migrer sans casser votre flux de travail.

Ce qui se reporte et ce qui ne se reporte pas

Nous avons testé cette migration avec une vraie spec de production : OpenAPI 3.0.3, 62 opérations réparties sur 13 tags, avec du contenu de démarrage, d'authentification et d'intégration rédigé dans les champs de description de la spec. Voici ce qui s'est passé à l'import.

La référence API est transférée sans aucune modification. Le manque concerne le contenu narratif.

Pourquoi vos champs de description ne s'affichent pas de la même manière

Redoc, le moteur de rendu derrière les docs de référence de Redocly, traite info.description comme un mini-document. Chaque titre Markdown qu'il contient devient une entrée de la barre latérale, c'est pourquoi les équipes y rédigent souvent l'intégralité de leurs guides « Démarrage » et « Authentification ». Les descriptions de tags s'affichent comme texte d'introduction en haut de chaque groupe de tags.

C'est une convention de Redoc, pas une partie de la spécification OpenAPI. La spec définit uniquement description comme une chaîne CommonMark. Apidog, comme la plupart des portails, conserve les guides sous forme de documents Markdown autonomes et réserve la spec à la référence. Une publication par défaut après import affiche uniquement la référence API, sans les guides que vous avez rédigés dans les champs de description.

La solution est un déplacement ponctuel : extrayez ce contenu du YAML vers des fichiers Markdown à côté. Ensuite, tout reste piloté par Git.

La structure cible du dépôt

Voici la structure que nous avons validée :

your-repo/
├── openapi.yaml              # source of truth for the API reference
└── docs/
    ├── getting-started.md
    ├── authentication.md
    └── embed-integration-guide.md

openapi.yaml pilote la référence API. Chaque fichier dans docs/ devient une page dans la barre latérale du portail. Les images référencées par ces fichiers Markdown peuvent vivre dans le même dépôt et se synchroniser avec eux.

Si vous utilisiez le sidebars.yaml de Redocly pour ordonner votre navigation, conservez-le comme référence. Vous définirez le même ordre une fois dans les paramètres du site de documentation d'Apidog.

Migration étape par étape

1. Auditez le contenu de vos champs de description

Avant de déplacer quoi que ce soit, voyez combien de contenu se trouve dans la spec. Avec yq :

# How long is the top-level description?
yq '.info.description' openapi.yaml | wc -w

# Which headings does it contain? Each one is a Redoc sidebar entry today.
yq '.info.description' openapi.yaml | grep -E '^#{1,3} '

# Which tags carry a description?
yq '.tags[] | select(.description != null) | .name' openapi.yaml

La liste des titres constitue votre future liste de fichiers dans docs/. Dans notre test, info.description s'est scindé en deux fichiers Markdown, et les descriptions de tags sont devenues des pages d'introduction par dossier plus un fichier Markdown supplémentaire.

2. Scindez info.description en fichiers Markdown

Copiez chaque section de premier niveau dans son propre fichier sous docs/. Conservez les titres, les exemples de code et les liens. Réduisez ensuite info.description dans la spec à un résumé d'un paragraphe, afin que le contenu ne vive qu'à un seul endroit.

Surveillez deux fonctionnalités propres à Redoc pendant la copie :

• Les balises Redoc comme <SecurityDefinitions /> ne s'affichent pas en dehors de Redoc. Remplacez-les par une courte section rédigée qui renvoie aux schémas de sécurité dans la référence.
• Les liens comme #tag/Payments pointent vers des ancres Redoc. Mettez-les à jour vers les URL de doc ou de dossier Apidog correspondantes après la première publication.

3. Connectez le dépôt en Spec-first Mode

Créez un projet en Spec-first Mode, connectez votre dépôt (GitHub, GitLab, Azure DevOps ou Bitbucket), pointez-le vers openapi.yaml et le dossier docs/, puis installez le webhook. À partir de là, un push vers la branche suivie met à jour le projet.

Après la première synchronisation, l'espace de travail Specs affiche votre spec et le reste du dépôt. L'onglet APIs liste les opérations analysées depuis openapi.yaml, Docs contient vos pages Markdown, et All files reflète le dépôt.

Le webhook est ce qui maintient ce flux de travail docs-as-code. Sans lui, vous devriez déclencher les synchronisations manuellement. Pour un rappel de son importance, consultez notre guide sur la documentation as code.

4. Publiez le site de documentation et définissez la navigation

Publiez un site de documentation à partir du projet et organisez la barre latérale. L'ordre que la plupart des utilisateurs de Redocly souhaitent, et celui que nous avons reproduit, est :

1. Getting Started
2. Authentication
3. Integration guides
4. API Reference (les dossiers d'endpoints issus de vos tags)

Les pages Markdown et les dossiers API se mélangent librement dans une même arborescence, ce qui vous permet de reproduire fidèlement votre barre latérale Redocly actuelle.

5. Ajoutez votre domaine personnalisé

Pointez un CNAME tel que developers.example.com vers le site de documentation. Les domaines personnalisés sont disponibles avec le plan gratuit.

Laissez votre agent de codage migrer les descriptions de tags avec Apidog CLI

Les descriptions de tags sont la partie la plus fastidieuse. Treize tags, cela signifie treize copier-coller, et vous devrez les refaire à chaque fois qu'une description de tag change pendant la transition. Confiez-le plutôt à votre agent de codage.

Apidog CLI donne à Claude Code, Codex, Cursor ou à tout agent en terminal un accès JSON structuré à votre projet, y compris aux dossiers d'endpoints. Configurez-le une fois :

npm install -g apidog-cli@latest
apidog auth login --with-token <YOUR_ACCESS_TOKEN>
npx -y skills add https://apidog.com

La dernière ligne installe la skill Apidog pour que votre agent connaisse les commandes sans deviner. Le guide d'installation couvre les jetons et les déploiements privés.

Donnez ensuite une seule instruction à votre agent :

Read openapi.yaml. For every tag with a description, find the matching endpoint folder in Apidog project <PROJECT_ID> and set that folder’s description to the tag’s description. Validate each payload with apidog cli-schema validate folder-update before writing. Show me the list of folders you changed.

Voici ce que l'agent exécute :

# Find the folder IDs that correspond to your tags
apidog folder list --project <PROJECT_ID> --type endpoint

# Check the payload shape instead of guessing it
apidog cli-schema get folder-update

# For each tag: write {"description": "..."} to a file, validate, then update
apidog cli-schema validate folder-update --file ./payments-folder.json
apidog folder update <FOLDER_ID> --project <PROJECT_ID> --type endpoint \
  --file ./payments-folder.json

Le schéma folder-update accepte name, parentId et description, et description est pris en charge sur les dossiers d'endpoints et de scénarios de test. Pour les guides qui n'appartiennent pas à un seul tag, l'agent peut utiliser apidog doc list et apidog doc create de la même manière, après avoir lu apidog cli-schema get doc-create.

Pour afficher l'introduction d'un dossier sur le site publié, définissez Folder Contents Displaying Setting dans les paramètres du dossier, sous Documentation Settings after Publication.

Une mise en garde honnête : exposer les descriptions de tags sous forme de pages d'introduction par catégorie fonctionne, mais repose sur un chemin peu documenté. Testez-le sur deux ou trois dossiers dans votre propre espace de travail avant de vous y fier pour l'ensemble. Pour aller plus loin dans le travail sur la spec piloté par agent, consultez utiliser Apidog CLI dans Claude Code et laisser un agent mettre à jour votre spec API.

Ce qui reste en dehors de Git

Un projet Spec-first conserve votre API et votre Markdown dans Git. Quelques paramètres du portail vivent dans l'interface Apidog et ne sont pas versionnés :

Ce sont des éléments à configurer une seule fois. Vous y touchez lorsque vous ajoutez une nouvelle section de premier niveau, pas à chaque modification de contenu. Redocly en conserve davantage dans redocly.yaml et sidebars.yaml, donc si vous relisez aujourd'hui les modifications de navigation dans des pull requests, prévoyez que cela bascule dans l'interface.

Offre et tarification

La configuration décrite ici tient dans le plan gratuit, domaine personnalisé inclus. Le plan gratuit couvre jusqu'à 4 membres d'équipe. Les plans payants ajoutent des éléments comme plusieurs sites de documentation par projet et des contrôles de visibilité personnalisés. Consultez la tarification Apidog pour les limites actuelles.

Redocly vs. Apidog après la migration

Le compromis est simple. Vous perdez la navigation définie en YAML. Vous gagnez le test, le mock et une CLI adaptée aux agents sur la même spec que celle dont provient votre documentation. Pour une comparaison CLI par CLI, lisez Apidog CLI vs Redocly CLI.

FAQ

Mes URL hébergées sur Redocly continueront-elles de fonctionner ? Pas automatiquement. Les chemins des pages changent. Si votre ancien portail comportait des URL de guides à fort trafic, ajoutez des redirections au niveau de votre DNS ou de votre proxy pour les pages principales après avoir basculé le domaine.

Dois-je réécrire ma spec OpenAPI ? Non. La spec s'importe telle quelle. Vous déplacez uniquement le contenu narratif de info.description et tags[].description vers des fichiers Markdown.

Puis-je conserver x-tagGroups ? Utilisez plutôt des dossiers pour le regroupement. Chaque tag devient un dossier, et vous pouvez imbriquer des dossiers pour reproduire vos groupes de tags.

Comment cela se compare-t-il à une migration depuis Stoplight ? La forme est similaire : spec dans Git, Markdown à côté, synchronisation par webhook. Consultez comment migrer de Stoplight vers Apidog si vous utilisez les deux outils.

Et si une étape se comporte différemment dans mon espace de travail ? Nos résultats proviennent d'un environnement de test. Relancez l'import d'abord sur une branche et comparez le portail publié avec votre portail actuel avant de basculer le DNS.

Faites la transition en un après-midi

Une migration de Redocly vers Apidog est essentiellement un déplacement de contenu. Votre spec s'importe telle quelle. Vos guides sortent des champs de description vers un dossier docs/ une seule fois. Un webhook maintient ensuite le tout synchronisé. Laissez votre agent gérer le travail répétitif des descriptions de tags avec Apidog CLI, et consacrez votre temps à vérifier le portail publié page par page.

Téléchargez Apidog et connectez votre dépôt au Spec-first Mode pour commencer la migration.