Si vous avez adopté Bruno, vous en connaissez déjà l'attrait. Vos collections sont des fichiers .bru simples dans votre dépôt Git, versionnés avec le code, sans nécessiter de compte cloud. C'est une réponse propre et axée sur l'offline pour les clients API qui veulent posséder vos données.
Mais tôt ou tard, quelqu'un pose une question à laquelle Bruno ne répond pas bien : « Où sont les docs ? Peux-tu m'envoyer un lien ? » C'est là que les équipes butent. Bruno est conçu pour envoyer des requêtes, pas pour publier un portail de documentation partageable. Ce guide aborde honnêtement la génération de documentation API avec Bruno, ce que Bruno vous offre, ce qu'il ne vous offre pas, et comment générer et héberger des docs à partir de votre spécification lorsque vous avez besoin d'une véritable URL à fournir aux consommateurs.
Ce dont les équipes ont réellement besoin en matière de documentation API
Avant de juger un outil, il est utile de définir l'objectif. Lorsque les gens parlent de « documentation API », ils désignent généralement trois choses qui fonctionnent ensemble :
- Une URL partageable. Les développeurs frontend, les partenaires et l'assurance qualité doivent pouvoir lire les docs sans cloner votre dépôt ni installer un client. Un lien dans Slack doit simplement fonctionner.
- Des docs qui restent synchronisées. Une documentation qui s'éloigne de l'API réelle est pire que l'absence de documentation, car elle oriente les gens avec confiance dans la mauvaise direction. Les docs doivent suivre la spécification.
- Une expérience interactive « essayez-le ». Lire les descriptions de points de terminaison, c'est bien ; envoyer une vraie requête contre le point de terminaison documenté, avec l'authentification et les exemples de charges utiles remplis, c'est ce qui transforme les docs en une référence utilisable.
Atteignez ces trois points et vos docs deviennent la source unique de vérité. Manquez-en un et les gens se rabattront sur des questions directes, ce qui n'est pas évolutif.
L'histoire de la documentation de Bruno
Soyons justes envers Bruno, car il fait bien certaines choses ici.
Les collections de Bruno sont lisibles par l'homme. Le format .bru est du texte brut, de sorte qu'un ingénieur parcourant le dépôt peut ouvrir un fichier de requête et voir la méthode, l'URL, les en-têtes et le corps. Bruno prend également en charge un bloc docs par requête et une vue de documentation Markdown dans l'application, afin que vous puissiez joindre du texte expliquant ce que fait un point de terminaison. Comme tout est dans Git, ces notes sont examinées lors des requêtes de tirage (pull requests) comme tout autre changement. Pour une équipe interne qui vit dans la base de code, c'est une forme de documentation légitime.
La lacune honnête est la publication. Bruno n'a pas de portail de documentation publique intégré, hébergé et généré automatiquement. Il n'y a pas de bouton « publier » qui transforme votre collection en un site web avec une URL stable et un domaine personnalisé. La vue des docs intégrée à l'application est visible par les personnes qui ont déjà installé Bruno et cloné la collection, ce qui est exactement le public qui a le moins besoin de docs.
Les équipes improvisent donc. Les solutions courantes incluent l'exportation de la collection ou d'un fichier OpenAPI et son alimentation dans un générateur de docs statiques séparé, la mise en place d'un site de docs dans CI, ou la maintenance d'un fichier README écrit à la main que quelqu'un met à jour de mémoire. Ceux-ci peuvent fonctionner, mais ils ajoutent un pipeline de construction à maintenir et un deuxième endroit où les informations peuvent dériver. La documentation n'est plus un résultat de première classe de l'outil avec lequel vous testez ; c'est un projet secondaire.
Le principe des « docs-as-code »
Une façon plus claire de penser à cela, et c'est une chose que les utilisateurs de Bruno croient déjà à moitié : traitez votre documentation comme un produit de votre spécification, et non comme un artefact séparé.
Dans un workflow docs-as-code, votre API est décrite une seule fois dans une spécification lisible par machine, généralement OpenAPI. Cette spécification vit dans Git, est examinée lors des requêtes de tirage (pull requests) et agit comme le contrat. La documentation, les serveurs mock et les SDK clients sont tous générés à partir de celle-ci. Lorsque le contrat change, le changement est examiné à un seul endroit, et tout ce qui en découle suit.
L'avantage est qu'il n'y a pas de tâche distincte « mettre à jour les docs » à oublier. Les docs sont un rendu de la spécification. Si la spécification est correcte et examinée, les docs sont correctes. C'est le principe que Bruno suggère en gardant les collections dans Git, mais il s'arrête avant l'étape de publication.
Générez et hébergez plutôt des docs à partir de votre spécification
C'est la lacune que Apidog est conçu pour combler. Apidog conserve le même modèle mental centré sur la spécification et compatible avec Git, puis ajoute la pièce que Bruno omet : il génère un site de documentation interactif et hébergé directement à partir de votre spécification, sans nécessiter de pipeline de construction séparé.
Pointez Apidog vers votre spécification OpenAPI et il produira automatiquement un portail de documentation. Le résultat est :
- Hébergé sur une URL partageable, afin que toute personne ayant le lien puisse lire les docs sans rien installer.
- Montable sur un domaine personnalisé, afin que les docs puissent se trouver à l'adresse
docs.votreentreprise.comet correspondre à votre marque. - Interactif, avec un panneau « essayez-le » intégré qui envoie de vraies requêtes en utilisant les paramètres, les en-têtes et l'authentification documentés.
- Généré à partir de la spécification, de sorte que les docs reflètent ce que l'API déclare réellement plutôt qu'une copie manuscrite qui peut dériver.
Parce que la même spécification pilote également les tests et le mocking d'Apidog, vous ne maintenez pas trois descriptions pour une seule API. Vous la décrivez une fois et la réutilisez.
Guide pas à pas : de la spécification à l'URL partageable
Voici la version courte de la publication de documentation à partir d'une spécification OpenAPI.
| Étape | Action | Résultat |
|---|---|---|
| 1 | Importez ou écrivez votre spécification OpenAPI dans Apidog | Les points de terminaison, schémas et exemples se remplissent automatiquement |
| 2 | Ouvrez les paramètres de documentation du projet | La documentation est générée à partir de la spécification, prête à être configurée |
| 3 | Choisissez la visibilité et (optionnellement) un domaine personnalisé | La documentation est publique, privée ou protégée par mot de passe |
| 4 | Publier | Un site de documentation hébergé et en direct est créé à une URL stable |
| 5 | Partagez le lien | Les consommateurs lisent la documentation et exécutent des requêtes « essayez-le » |
Si vous avez déjà une collection Bruno, vous pouvez d'abord la convertir en OpenAPI, puis importer cette spécification. À partir de là, l'étape de publication est la même. Le fait est que générer et héberger la documentation est un atout, et non un pipeline que vous assemblez vous-même.
Maintenir la synchronisation des documents à mesure que la spécification change
Une URL de documentation n'est utile que si elle reste précise. Le mode d'échec avec les configurations improvisées est que quelqu'un déploie une modification de point de terminaison et oublie les documents.
Lorsque les documents sont générés à partir de la spécification, ce risque diminue. Vous modifiez la spécification, la modification de la spécification passe par une révision comme toute autre modification de code, et les documents publiés reflètent le nouvel état. Il n'y a pas de document parallèle à retenir. Ajoutez un champ à un schéma de réponse et il apparaît dans les documents ; dépréciez un point de terminaison et les documents le signalent. Le travail que vous faites déjà pour maintenir le contrat correct est le même travail qui maintient les documents corrects.
C'est le gain pratique du principe des « docs-as-code » : la justesse devient un effet secondaire d'un workflow que vous voudriez de toute façon, plutôt qu'une corvée distincte qui dépend de la discipline.
FAQ
Bruno peut-il générer et héberger de la documentation API publique ?
Bruno fournit des fichiers de collection .bru lisibles et une vue de documentation Markdown intégrée à l'application, tous deux révisés dans Git. Il n'inclut pas de portail de documentation publique intégré, hébergé et généré automatiquement avec une URL partageable. Pour publier des documents publics à partir de Bruno, les équipes exportent généralement une spécification et exécutent un générateur de documents statiques séparé, ce qui ajoute un pipeline à maintenir.
Comment obtenir une URL de documentation partageable à partir de mon API ?
Décrivez votre API dans une spécification OpenAPI, puis utilisez un outil qui génère des documents hébergés à partir de celle-ci. Dans Apidog, vous importez la spécification, configurez la visibilité, joignez éventuellement un domaine personnalisé, puis publiez. Le résultat est un site de documentation en direct à une URL stable, avec un panneau interactif « essayez-le », que vous pouvez partager directement.
Dois-je abandonner mes collections Bruno pour publier de la documentation ?
Non. Vous pouvez convertir une collection Bruno existante en OpenAPI et importer cette spécification dans un outil de documentation. Vos points de terminaison, schémas et exemples sont transférés, et vous conservez la spécification sous contrôle de version. La migration se fait au niveau de la couche de spécification, de sorte que les habitudes de « docs-as-code » que vous avez développées avec Bruno s'appliquent toujours.