Expliquez le travail technique avec du code et des tableaux de champs
Gardez l’explication d’un endpoint, son exemple de requête et sa réponse près de la discussion de conception. API Documentation fournit du texte modifiable et des objets Code block natifs pour HTTP et JSON. Adaptez le contrat d’exemple, ajoutez un tableau de champs si la comparaison aide et conservez des extraits lisibles. Le canvas devient une référence technique visuelle qui évolue avec l’interface.
Canvas → Templates → API Documentation → Code block → Code languageCe que vous apprendrez
- Modifier les blocs natifs et choisir leur langage d’affichage.
- Harmoniser les exemples de requête, de succès et d’erreur.
- Comparer les exigences des champs dans une grille modifiable.
Capturé dans Boilerrum avec un projet d’exemple. L’interface est affichée en anglais.
Dans ce guide
01
Partir de la référence d’endpoint
Dans Templates, recherchez API Documentation et choisissez Use template. Examinez Request, Response / 201 Created, Request fields et Error / 400 Bad Request. Remplacez titre, endpoint et explications par le contrat à discuter. L’adresse api.example.com et les données de tâche sont des exemples : relisez-les avant d’utiliser le tableau comme référence.
02
Modifier le code de la requête
Sélectionnez le Code block de requête et double-cliquez sur son aperçu, ou donnez le focus au bloc sélectionné et appuyez sur Entrée ou F2. Saisissez la requête dans Code content. Avec Code language dans l’en-tête, choisissez HTTP, JSON ou un autre langage adapté. Échap revient à l’aperçu ; vérifiez le contenu et le langage de ce bloc.
03
Expliquer ensemble succès et erreurs
Modifiez séparément les blocs de réponse et d’erreur en choisissant le Code language adapté. Harmonisez noms de champs, identifiants et statuts avec l’explication de la requête. Ajoutez près d’une erreur une courte phrase sur l’action suivante de l’appelant. Ces exemples servent à la revue documentaire ; vérifiez-les par rapport au contrat maintenu par l’équipe.
04
Comparer les exigences des champs
Pour comparer les champs, ouvrez Grid tools et choisissez quatre lignes et quatre colonnes. Double-cliquez sur les cellules pour saisir Field, Type, Required et Meaning en en-tête, puis décrivez trois champs de requête. Placez la grille près du code et comparez les noms aux extraits. Gardez les lignes de texte du modèle uniquement si elles apportent une explication utile.
05
Vérifier la référence et la garder utile
Quittez l’édition du code et examinez la référence avec Fit view. Vérifiez les longues lignes, les petits textes du tableau et la cohérence des exemples de succès et d’erreur avec les descriptions des champs. Enregistrez le canvas. Pour une revue, ajoutez un cadre et exportez-le via Present → Frame options, puis vérifiez le fichier tout en conservant les blocs modifiables.
Votre canvas explique l’endpoint avec des exemples cohérents de requête, de réponse et d’erreur, accompagnés d’une comparaison lisible des champs. L’équipe peut revoir le contrat visuellement et modifier le contenu technique sur place.