Comment convertir les Spécifications OpenAPI en documentation Markdown propre automatiquement

Votre fichier OpenAPI est la source de vérité pour votre API. Il liste chaque chemin, chaque paramètre, chaque forme de réponse. Le problème est que presque personne dans votre équipe ne veut lire du YAML ou du JSON brut. Un ingénieur backend souhaite une référence rapide des points d'API dans le dépôt. Un développeur frontend souhaite un tableau des champs de requête qu'il peut parcourir dans une pull request. Un rédacteur technique souhaite quelque chose qu'il peut coller dans un wiki sans retaper tout le schéma.

Le Markdown est le format qui convient à tous ces lecteurs. Il s'affiche sur GitHub, dans Confluence, dans un générateur de site statique et dans un éditeur de texte brut. La tâche récurrente est donc la suivante : prendre un openapi.yaml qui existe déjà et le transformer en Markdown propre que les humains consultent réellement. Le faire à la main est lent et se décale dès que quelqu'un ajoute un point d'API. Le faire automatiquement est la seule version qui survit au contact d'un véritable cycle de publication.

Pourquoi générer du Markdown à partir d'OpenAPI

Un document OpenAPI est conçu pour les machines. Les outils l'analysent pour générer des clients, exécuter des tests de contrat, valider des requêtes et afficher des documents interactifs. Cette lisibilité par les machines est l'objectif principal, et elle mérite d'être protégée. Si vous souhaitez rafraîchir vos connaissances sur la manière de maintenir la spécification elle-même correcte, le guide des outils de validation OpenAPI couvre le linting avant même de générer quoi que ce soit à partir de celle-ci.

Le Markdown résout un problème différent : la distribution aux humains dans des endroits qui n'exécutent pas de moteur de rendu OpenAPI. Quelques cas concrets reviennent encore et encore.

• Un fichier README.md ou un dossier /docs dans le dépôt, afin qu'un nouveau contributeur voie la liste des points d'API sans quitter la base de code.
• Une description de pull request qui doit montrer ce qu'un nouveau point d'API accepte et retourne.
• Une page Confluence ou Notion où l'équipe élargie, y compris les non-ingénieurs, examine le contrat.
• Un site de documentation statique construit avec Docusaurus, MkDocs ou Hugo, qui acceptent tous le Markdown en entrée.

Le mot clé est automatiquement. Un fichier Markdown que vous écrivez une fois et oubliez est obsolète dès le sprint suivant. Un fichier Markdown régénéré à partir de la spécification à chaque modification reste fidèle au contrat gratuitement. C'est la différence entre des documents auxquels les gens font confiance et des documents que les gens apprennent à ignorer.

Les méthodes de conversion, du rapide à l'infaillible

Il n'existe pas de commande officielle unique livrée avec OpenAPI pour produire du Markdown. Il existe plutôt un petit écosystème de convertisseurs ainsi que des moteurs de documentation intégrés aux plateformes API. Voici le panorama, classé approximativement par la quantité de configuration que chacun nécessite.

Choisissez en fonction du niveau de contrôle dont vous avez besoin et de l'endroit où le résultat doit être livré. Les sections suivantes montrent chacun d'eux en action.

Méthode 1 : un convertisseur open source en une ligne

Le chemin le plus rapide est un convertisseur dédié. Deux bien connus couvrent les mondes Node et Python.

Pour un projet Node, openapi-to-md prend un document v2 ou v3 en YAML ou JSON et écrit un fichier Markdown structuré. Vous pouvez l'exécuter sans installation globale :

npx openapi-to-md openapi.yaml api-reference.md

Pour une chaîne d'outils Python, openapi-markdown fait le même travail avec une installation pip et une seule commande :

pip install openapi-markdown
openapi2markdown openapi.yaml api-reference.md

Les deux lisent la spécification, parcourent chaque chemin et chaque schéma, et émettent un fichier Markdown avec des titres par point d'API et des tableaux pour les paramètres et les réponses. L'argument du fichier de sortie est optionnel dans certains de ces outils ; omettez-le et ils utiliseront par défaut le nom d'entrée avec une extension .md. C'est suffisant pour une référence de dépôt que vous régénérez à la demande.

Le compromis avec les convertisseurs rapides est le contrôle de la mise en page. Vous obtenez leur structure, pas la vôtre. Si leurs tableaux par défaut correspondent à la façon dont votre équipe lit les documents, vous avez terminé en une ligne. Si vous avez besoin d'exemples de code dans cinq langages ou d'un ordre de section spécifique, vous voudrez la méthode suivante.

Méthode 2 : Widdershins pour des documents thémables avec des exemples de code

Widdershins est l'outil Node établi pour transformer un fichier OpenAPI ou Swagger en Markdown compatible avec Slate. C'est celui vers lequel se tourner lorsque vous souhaitez des onglets de code de langage et un modèle personnalisable, et lorsque le Markdown alimente un générateur de site statique comme Docusaurus ou MkDocs.

Installez-le et exécutez la conversion de base :

npm install -g widdershins
widdershins openapi.yaml -o api-reference.md

Ajoutez des langages pour les exemples de code et supprimez l'en-tête front-matter lorsque vous transmettez la sortie vers un endroit qui ajoute le sien :

widdershins --language_tabs 'shell:cURL' 'python:Python' 'javascript:JavaScript' \
  --omitHeader openapi.yaml -o api-reference.md

Widdershins utilise un système de modèles, vous pouvez donc remplacer la mise en page de n'importe quelle section au lieu d'accepter celle par défaut. Cela en fait le pont entre un dump brut et un site de documentation entièrement construit à la main. Le coût est que vous possédez désormais un modèle et une étape de construction, ce qui est bien pour un dépôt de documentation mais excessif pour un README rapide.

Méthode 3 : un script personnalisé lorsque vous avez besoin d'une mise en page exacte

Parfois, aucun des convertisseurs prêts à l'emploi ne produit la forme que vous souhaitez. Peut-être avez-vous besoin d'un fichier Markdown par balise, ou d'un index de points d'API compact, ou de tableaux de schémas qui correspondent à un guide de style interne. Dans ce cas, analysez la spécification vous-même et créez le modèle de sortie. La spécification n'est que des données structurées, c'est donc moins de travail qu'il n'y paraît.

Une version Node minimale qui liste chaque opération ressemble à ceci :

import { readFileSync, writeFileSync } from "node:fs";
import yaml from "js-yaml";

const spec = yaml.load(readFileSync("openapi.yaml", "utf8"));
const lines = [`# ${spec.info.title}`, "", spec.info.description ?? "", ""];

for (const [path, methods] of Object.entries(spec.paths)) {
  for (const [method, op] of Object.entries(methods)) {
    lines.push(`## ${method.toUpperCase()} ${path}`);
    lines.push("");
    lines.push(op.summary ?? "");
    lines.push("");
    const params = op.parameters ?? [];
    if (params.length) {
      lines.push("| Name | In | Required | Description |");
      lines.push("| ---- | -- | -------- | ----------- |");
      for (const p of params) {
        lines.push(`| ${p.name} | ${p.in} | ${p.required ? "yes" : "no"} | ${p.description ?? ""} |`);
      }
      lines.push("");
    }
  }
}

writeFileSync("api-reference.md", lines.join("\n"));

C'est environ quarante lignes pour un contrôle total sur la sortie. Vous décidez des titres, des colonnes du tableau, de la division des fichiers. L'inconvénient est la maintenance : lorsque la version OpenAPI que vous ciblez ajoute une fonctionnalité, votre script doit l'apprendre. Pour un style interne stable, ce compromis en vaut généralement la peine. Pour une couverture large des spécifications, utilisez plutôt un convertisseur maintenu. Si vous hésitez entre script et achat, le tour d'horizon des générateurs de documentation API avec exportation Markdown compare les options maintenues côte à côte.

Méthode 4 : garder la spécification, les documents et les tests ensemble dans Apidog

Les convertisseurs ci-dessus partagent tous un angle mort. Ils transforment une spécification en Markdown, puis les deux divergent. Quelqu'un modifie l'API, oublie de relancer le convertisseur, et le Markdown ment. La solution est d'arrêter de traiter la spécification comme un fichier vivant seul et de commencer à la traiter comme faisant partie d'un espace de travail où les documents et les tests sont mis à jour avec elle.

C'est le modèle qu'utilise Apidog. Vous importez votre openapi.yaml existant, et Apidog lit chaque chemin, schéma et exemple dans un projet. À partir de là, vous obtenez une documentation API rendue et hébergée, générée directement à partir de la spécification importée, sans étape de build séparée. Le flux d'importation complet est couvert dans comment importer Swagger ou OpenAPI et générer des requêtes, et le chemin de la spécification à la référence publiée dans la génération automatique de documentation API à partir d'OpenAPI.

Deux choses différencient cela d'un convertisseur ponctuel.

• Premièrement, la documentation prend en charge vos propres blocs de contenu Markdown. La référence des points d'API générée provient de la spécification, et vous superposez du Markdown écrit à la main autour d'elle : une page de démarrage, des notes d'authentification, des entrées de journal des modifications. Les conseils pour créer de la documentation avec Apidog Markdown expliquent ce côté de la rédaction. Vous ne choisissez donc pas entre des documents générés et des documents écrits ; vous obtenez les deux au même endroit.
• Deuxièmement, la même spécification importée devient la base des scénarios de test. Vous construisez des requêtes et des assertions contre les points d'API définis par la spécification, puis vous les exécutez pour prouver que l'API en direct correspond toujours au contrat qui a produit vos documents. Cela ferme la boucle de dérive : si l'API change et rompt le contrat, les tests échouent, et vous savez que les documents sont obsolètes avant même qu'un lecteur ne le découvre.

Pour suivre, téléchargez Apidog, importez une spécification et ouvrez les documents générés dans le même projet. Le but n'est pas qu'Apidog imprime un fichier .md sur le disque. C'est que la spécification, les documents lisibles par l'homme et les tests qui maintiennent les deux honnêtes cessent d'être trois fichiers déconnectés.

Rendez-le automatique : régénérez le Markdown en CI

Un convertisseur que vous exécutez à la main est un convertisseur que vous oubliez. Toute la valeur de la génération de Markdown à partir d'OpenAPI n'apparaît que lorsque la génération s'exécute d'elle-même, à chaque modification. Le modèle est simple : à chaque push qui touche la spécification, régénérez le Markdown et commitez-le, ou publiez-le.

Voici un job GitHub Actions qui régénère la référence chaque fois que openapi.yaml change :

name: Generate API docs

on:
  push:
    paths:
      - "openapi.yaml"

jobs:
  docs:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: "20"
      - name: Convert spec to Markdown
        run: npx openapi-to-md openapi.yaml docs/api-reference.md
      - name: Commit regenerated docs
        run: |
          git config user.name "docs-bot"
          git config user.email "docs-bot@users.noreply.github.com"
          git add docs/api-reference.md
          git diff --staged --quiet || git commit -m "docs: regenerate API reference"
          git push

Désormais, le Markdown ne peut jamais s'éloigner de plus d'un commit de la spécification. La même idée fonctionne dans GitLab CI ou tout autre exécuteur avec Node ou Python ; remplacez l'étape de conversion par widdershins ou votre script. Il y a un autre élément qui mérite d'être intégré. Les documents régénérés ne sont fiables que si la spécification dont ils proviennent est toujours exacte. C'est là qu'une exécution de test en ligne de commande trouve sa place dans le même pipeline. L'interface CLI d'Apidog exécute les scénarios de test que vous avez construits contre votre spécification importée, sans interface graphique, avec une seule commande :

npm install -g apidog-cli
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e 1629989 -r cli

Il se termine avec un code non nul si une assertion échoue, ce qui fait échouer la build, ce qui vous empêche de publier des documents décrivant une API qui ne se comporte plus de cette manière. L'ensemble des options se trouve dans la référence des commandes apidog run, et la configuration plus large du pipeline dans le guide complet de l'interface CLI d'Apidog. Associez la génération de documentation à un test de contrat et les deux se renforcent mutuellement : la spécification produit les documents, et le test prouve la spécification.

Nettoyage du Markdown généré

Le Markdown généré est rarement parfait du premier coup. Quelques habitudes le maintiennent lisible.

• Supprimez le front matter auto-généré lorsque le moteur de rendu cible n'en veut pas. Widdershins le fait avec --omitHeader ; pour d'autres outils, un rapide sed sur le haut du fichier fonctionne.
• Décidez d'une division de fichiers. Un seul fichier Markdown géant convient pour un README. Pour un site de documentation, divisez par balise ou par ressource afin que chaque page soit courte.
• Gardez des exemples réels. La plupart des convertisseurs extraient les valeurs d'exemple directement de la spécification, donc la qualité de vos documents générés suit la qualité de vos examples dans OpenAPI. De meilleurs exemples en entrée, de meilleurs documents en sortie.
• Régénérez, ne modifiez pas à la main. Au moment où vous modifiez manuellement le Markdown généré, la conversion suivante vous écrase. Placez le contenu écrit à la main dans des fichiers séparés et laissez le générateur ne gérer que la section de référence.

Si votre spécification est elle-même désordonnée, corrigez-la à la source. Des spécifications plus propres produisent des documents plus propres, et l'article sur les outils de validation OpenAPI montre comment détecter les lacunes qui produisent une sortie laide.

Choisir la bonne méthode pour votre équipe

Adaptez l'outil à l'endroit où le Markdown doit aller et au niveau de contrôle dont vous avez besoin.

• Vous voulez une référence de dépôt en une seule commande et vous n'êtes pas exigeant sur la mise en page : utilisez openapi-to-md ou openapi-markdown.
• Vous construisez un site de documentation avec des exemples de code et souhaitez un modèle thémable : utilisez Widdershins.
• Vous avez un guide de style interne que les convertisseurs ne peuvent pas égaler : écrivez un petit script sur la spécification parsée.
• Vous voulez que les documents, la spécification et les tests qui les maintiennent honnêtes vivent ensemble dans un seul espace de travail, avec une sortie hébergée et sans build séparé à gérer : importez la spécification dans Apidog.

Ces options ne sont pas mutuellement exclusives. De nombreuses équipes utilisent Apidog comme source de vérité pour la spécification et sa documentation hébergée, puis exécutent un convertisseur en CI pour déposer une référence Markdown dans le dépôt pour une lecture hors ligne. La spécification reste canonique ; le Markdown est un artefact dérivé que vous pouvez régénérer à tout moment.

En résumé

La conversion d'OpenAPI en Markdown est un problème résolu tant que vous traitez la spécification comme la source et le Markdown comme un fichier dérivé. Pour une référence de dépôt rapide, un convertisseur en une ligne comme openapi-to-md fait le travail. Pour un site de documentation thémable, Widdershins offre des modèles et des onglets de code. Pour une mise en page interne exacte, un court script sur la spécification parsée l'emporte. Et lorsque vous souhaitez que la spécification, les documents rendus et les tests qui les maintiennent synchronisés vivent ensemble, l'importation dans Apidog élimine la dérive qui ruine toutes les autres approches au fil du temps.

Quoi que vous choisissiez, automatisez-le. Générez le Markdown en CI à chaque modification de spécification, et les documents que votre équipe lit correspondront toujours à l'API qu'ils décrivent.