Si vous avez adopté Bruno, vous en connaissez déjà l’intérêt : vos collections sont des fichiers .bru simples, stockés dans Git, versionnés avec le code, sans compte cloud obligatoire. C’est un bon choix pour les équipes qui veulent garder leurs données API en local et travailler offline.
Mais une limite apparaît vite : comment partager une documentation API avec une URL ? Bruno est conçu pour envoyer et organiser des requêtes, pas pour publier un portail de documentation hébergé. Voici comment penser la documentation API avec Bruno, où sont ses limites, et comment générer une documentation partageable à partir d’une spécification OpenAPI.
Ce qu’une documentation API doit fournir
Avant de choisir un outil, définissez le résultat attendu. Une documentation API utile doit généralement couvrir trois besoins.
- Une URL partageable : les développeurs frontend, les partenaires ou la QA doivent pouvoir lire la documentation sans cloner un dépôt ni installer un client API.
- Une documentation synchronisée avec l’API : si la documentation diverge de l’implémentation ou de la spécification, elle devient une source d’erreurs.
- Une expérience interactive : les consommateurs doivent pouvoir tester un endpoint documenté avec les bons paramètres, en-têtes, exemples de payload et règles d’authentification.
Si l’un de ces points manque, les équipes finissent souvent par poser les mêmes questions sur Slack ou par maintenir des fichiers README à la main.
Ce que Bruno permet de faire
Bruno fournit une base saine pour travailler avec des collections versionnées.
Les fichiers .bru sont lisibles par l’humain. Un développeur peut ouvrir une requête dans le dépôt et retrouver :
- la méthode HTTP ;
- l’URL ;
- les en-têtes ;
- le corps de requête ;
- les variables ou paramètres associés.
Bruno permet aussi d’ajouter un bloc docs par requête et d’afficher cette documentation Markdown dans l’application. Comme tout reste dans Git, les changements peuvent être relus dans les pull requests.
Exemple simplifié d’une requête Bruno :
meta {
name: Create user
type: http
}
post {
url: {{baseUrl}}/users
body: json
}
headers {
Content-Type: application/json
}
body:json {
{
"name": "Alice",
"email": "alice@example.com"
}
}
docs {
Crée un nouvel utilisateur avec un nom et une adresse e-mail.
}
Pour une équipe interne qui travaille déjà dans le dépôt, cela peut suffire comme documentation de proximité.
La limite : publier une documentation publique
La limite principale de Bruno est la publication.
Bruno ne fournit pas de portail de documentation publique hébergé et généré automatiquement. Il n’y a pas de bouton permettant de transformer une collection en site web avec :
- une URL stable ;
- un domaine personnalisé ;
- une expérience interactive dans le navigateur ;
- une documentation générée automatiquement à partir de la spécification.
La vue de documentation intégrée à Bruno est utile pour les personnes qui ont déjà installé Bruno et cloné la collection. Mais ce ne sont pas forcément les personnes qui ont le plus besoin d’une documentation accessible.
En pratique, les équipes contournent souvent cette limite avec l’une de ces approches :
- exporter une collection ou une spécification OpenAPI ;
- générer un site statique avec un outil séparé ;
- publier ce site via CI/CD ;
- maintenir un
READMEou une documentation manuelle.
Ces solutions peuvent fonctionner, mais elles ajoutent un pipeline et une surface de maintenance supplémentaire.
Utiliser une approche docs-as-code
Une approche plus robuste consiste à traiter la documentation comme un rendu de la spécification API, et non comme un document séparé.
Dans un workflow docs-as-code, l’API est décrite dans une spécification lisible par machine, généralement OpenAPI.
Cette spécification peut ensuite servir à générer :
- la documentation ;
- les mocks ;
- les tests ;
- éventuellement des SDK ou clients.
Le principe est simple : vous maintenez le contrat API à un seul endroit. La documentation est générée à partir de ce contrat.
Exemple minimal de spécification OpenAPI :
openapi: 3.0.3
info:
title: Users API
version: 1.0.0
paths:
/users:
post:
summary: Créer un utilisateur
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- name
- email
properties:
name:
type: string
email:
type: string
format: email
responses:
"201":
description: Utilisateur créé
Avec ce modèle, le workflow devient plus prévisible :
- modifier la spécification ;
- relire la modification dans Git ;
- générer ou mettre à jour la documentation ;
- publier une version synchronisée.
Générer et héberger la documentation avec Apidog
C’est le rôle qu’Apidog peut remplir : partir d’une spécification API et générer une documentation interactive hébergée.
À partir d’une spécification OpenAPI, Apidog peut produire un portail de documentation avec :
- une URL partageable ;
- une configuration de visibilité ;
- la possibilité d’utiliser un domaine personnalisé ;
- un panneau interactif pour tester les requêtes ;
- une documentation générée à partir de la spécification.
L’objectif est d’éviter de maintenir séparément la collection, la documentation et les mocks. La spécification devient la source de vérité.
Guide pas à pas : de la spécification à l’URL partageable
Voici un workflow simple pour publier une documentation API à partir d’une spécification OpenAPI.
| Étape | Action | Résultat |
|---|---|---|
| 1 | Importez ou écrivez votre spécification OpenAPI dans Apidog | Les endpoints, schémas et exemples sont remplis à partir de la spécification |
| 2 | Ouvrez les paramètres de documentation du projet | La documentation générée est prête à être configurée |
| 3 | Choisissez la visibilité et, si nécessaire, un domaine personnalisé | La documentation peut être publique, privée ou protégée par mot de passe |
| 4 | Publiez la documentation | Un site de documentation hébergé est disponible à une URL stable |
| 5 | Partagez le lien | Les consommateurs peuvent lire la documentation et tester les requêtes |
Si vous partez d’une collection Bruno, le workflow peut ressembler à ceci :
Collection Bruno
↓
Export ou conversion vers OpenAPI
↓
Import dans Apidog
↓
Génération de la documentation
↓
Publication d’une URL partageable
Le point important : la documentation publiée ne doit pas être un document manuel déconnecté de l’API. Elle doit être générée depuis le contrat.
Maintenir la documentation synchronisée
Une URL de documentation n’a de valeur que si elle reste exacte.
Avec une approche basée sur la spécification, le processus de mise à jour devient plus simple :
- vous modifiez l’endpoint dans la spécification ;
- vous faites relire la modification dans une pull request ;
- la documentation générée reflète la nouvelle version du contrat.
Par exemple, si vous ajoutez un champ à une réponse :
responses:
"200":
description: Liste des utilisateurs
content:
application/json:
schema:
type: array
items:
type: object
properties:
id:
type: string
name:
type: string
email:
type: string
createdAt:
type: string
format: date-time
La documentation doit afficher ce nouveau champ parce qu’elle est générée depuis la même source.
C’est l’intérêt pratique du docs-as-code : vous n’avez plus une tâche séparée “mettre à jour la documentation”. La mise à jour du contrat API entraîne la mise à jour de la documentation.
FAQ
Bruno peut-il générer et héberger une documentation API publique ?
Bruno fournit des fichiers .bru lisibles et une vue de documentation Markdown dans l’application. Ces éléments peuvent être versionnés dans Git. En revanche, Bruno ne fournit pas de portail de documentation publique hébergé et généré automatiquement avec une URL partageable.
Pour publier une documentation publique à partir de Bruno, il faut généralement exporter ou convertir vers une spécification, puis utiliser un générateur ou une plateforme de documentation.
Comment obtenir une URL de documentation partageable ?
Décrivez votre API dans une spécification OpenAPI, puis utilisez un outil capable de générer une documentation hébergée à partir de cette spécification.
Dans Apidog, le workflow consiste à :
- importer la spécification ;
- configurer la documentation ;
- choisir la visibilité ;
- publier ;
- partager l’URL.
Dois-je abandonner mes collections Bruno ?
Non. Vous pouvez conserver vos habitudes Git et convertir une collection Bruno existante en OpenAPI lorsque vous avez besoin d’une documentation hébergée.
L’important est de placer la spécification au centre du workflow. Bruno peut rester utile pour certaines équipes, tandis qu’un outil de documentation peut prendre le relais pour publier une URL exploitable par les consommateurs de l’API.
Top comments (0)