Documentation OpenAPI en Markdown
Convertissez un document OpenAPI ou Swagger en documentation de référence lisible en Markdown.
Documentation OpenAPI en Markdown
Collez un document OpenAPI 3 ou Swagger 2 — en JSON ou YAML — et cet outil le convertit en une référence API Markdown que vous pouvez insérer directement dans un README, une page wiki ou un site de documentation. Chaque opération devient sa propre section, transformant une spécification qu'une machine seule pourrait confortablement lire en quelque chose qu'un collègue ou un nouveau développeur peut parcourir rapidement.
Le résultat inclut une table des matières avec des liens vers chaque groupe et endpoint, un tableau de paramètres (ou une liste simple) pour les paramètres de chemin, requête, en-tête et cookie, un exemple de corps de requête généré, un tableau des codes de réponse avec leurs descriptions, et un corps de réponse d'exemple du premier schéma correspondant. Regroupez les endpoints par balise ou par le premier segment de leur chemin, choisissez si les exemples de requête se rendront sous forme de corps JSON ou de commande curl prête à l'emploi, et sélectionnez la profondeur des titres d'endpoint pour que le résultat s'intègre dans un document existant. Un commutateur inclut ou exclut les endpoints dépréciés ; un autre exporte chaque schéma sous composants (ou les définitions de Swagger) comme sa propre section à la fin.
Les pointeurs "$ref" au sein du même fichier sont suivis automatiquement pour les paramètres, les corps de requête/réponse et les schémas, ce qui permet à une spécification qui s'appuie sur les composants de produire des tableaux et des exemples complets plutôt que des chaînes $ref brutes. Les références vers un autre fichier ou une URL sont laissées intactes, car rien ici n'effectue jamais de requête réseau. Si le Markdown généré dépasse la limite de sortie de l'outil, vous recevez un message clair au lieu d'un onglet gelé.
Tout s'exécute localement dans votre navigateur — votre spécification API, qui décrit souvent des systèmes que vous ne voulez pas exposer, n'est jamais chargée nulle part. Copiez le Markdown, téléchargez-le en tant que fichier .txt ou envoyez-le à un autre outil pour continuer à travailler dessus.