Chaque article endpoint dans votre espace de travail de documentation API propose un ensemble d’options pour ajouter du contenu personnalisé, configurer les paramètres de l’article, collaborer avec votre équipe et contrôler l’accès. Cet article couvre tout ce qui est disponible sur une page d’article endpoint.
Ajout de contenu personnalisé aux articles de terminaison
Vous pouvez ajouter et formater du contenu personnalisé directement dans les pages de terminaison de votre API en utilisant l’éditeur intégré. C’est utile pour ajouter des notes d’utilisation, des exemples de code ou du contexte qui ne sont pas capturés dans votre spécification OpenAPI.
Pour ajouter du contenu à une page endpoint :
- Naviguez dans la documentation de l’API ({ }) dans la barre de navigation de gauche.
- Ouvrez l’article de point final que vous souhaitez modifier.
- Cliquez sur l’icône (+) pour insérer un bloc éditeur sous le contenu généré par la spécification.
- Entrez votre contenu et formatez-le en utilisant les options de la barre d’outils.
Votre contenu est sauvegardé automatiquement. Tout contenu personnalisé que vous ajoutez est conservé lorsque vous régénérez ou resynchronisez votre documentation API.
Barre d’outils de l’éditeur
L’éditeur d’articles de point final prend en charge les options de mise en forme de base - gras, italique et souligné, ainsi que la possibilité d’insérer un lien, d’attacher un fichier ou d’intégrer une image. Ces options sont disponibles dans la barre d’outils en haut du bloc éditeur.
Le contenu personnalisé ajouté aux pages endpoint est conservé lorsque vous régénérez ou resynchronisez votre documentation API.
Paramètres de l’article
Chaque article de point final dispose d’un panneau de paramètres d’article accessible depuis l’icône (⋯) dans la barre de navigation supérieure de l’éditeur. Cela vous donne accès à des options de configuration supplémentaires pour l’article.
Puisque chacun de ces univers dispose de son propre article dédié, cette section propose un bref aperçu et des liens vers la documentation pertinente.
| Cadre | Ce que ça fait |
|---|---|
| Rappel d’avis | Fixez un rappel pour relire l’article à intervalles précis, soit en le marquant pour la révision, soit en programmant un rappel. |
| Champs personnalisés | Ajoutez des champs de métadonnées personnalisés à l’article. |
| GÉO/SEO | Configurez les paramètres SEO, y compris le méta-titre, la description et le géo-ciblage. |
| Visibilité en recherche | Contrôlez si l’article apparaît dans les résultats de recherche. |
| Tags | Ajoutez des tags à l’article pour une meilleure détection. |
| Labels | Appliquez des étiquettes pour catégoriser et filtrer les articles. |
| Articles connexes | Mettez des liens entre articles liés que les lecteurs pourraient trouver utiles. |
| Image à la une | Définissez une image en avant pour l’article. |
| Accessoires | Ajoutez des pièces jointes à l’article. |
| Indicateur de statut | Définissez un indicateur de statut pour signaler l’état de l’article. |
| Préférences | Configurez les préférences au niveau des articles. |
| Type d’éditeur | Changez de type d’éditeur pour l’article. |
| Marquez comme déprécié | Marquez l’article comme obsolète pour signaler qu’il n’est plus activement maintenu. |
Pour des instructions détaillées sur chaque cadre, consultez l’article sur la gestion des articles .
Options d’articles de point de terminaison
En cliquant droitement sur un article de point final dans la rubrique Catégories & Articles, vous obtenez les options suivantes :
| Option | Ce que ça fait |
|---|---|
| Publier | Publiez l’article sur le point final sur le site de la base de connaissances. |
| À publier plus tard | Programmez la publication de l’article à une date et une heure précises. |
| Renom | Renommer l’article sur le point final. |
| Sécurité | Configurez qui peut accéder à l’article à la fois depuis le portail et le site de la base de connaissances. |
Discussions
Le panneau de discussion vous permet d’avoir des conversations directement avec votre équipe sur un article de point final. C’est utile pour laisser des retours, signaler des problèmes ou coordonner des mises à jour sans laisser la documentation.
Pour ouvrir le panneau de discussion, cliquez sur l’icône Discussion dans la barre de navigation supérieure de l’éditeur. Vous pouvez lancer une nouvelle conversation et utiliser @ pour mentionner un membre spécifique de l’équipe.
FAQ
Le contenu personnalisé est-il conservé lorsque je resynchronise ma documentation API ?
Oui. Tout contenu personnalisé que vous ajoutez aux articles endpoint est conservé lorsque vous régénérez ou resynchronisez votre documentation API. Seul le contenu généré par la spécification est mis à jour.
Puis-je télécharger des articles en PDF via l’API ?
Actuellement, il n’existe aucune option pour télécharger des articles en PDF via les points de terminaison de l’API.
Que se passe-t-il avec le contenu personnalisé lorsqu’un point de terminaison est supprimé lors de la resynchronisation ?
Lorsqu’un point de terminaison est retiré de votre spec et qu’une resynchronisation est effectuée, l’article du point de terminaison et tout son contenu personnalisé sont définitivement supprimés. Les points de terminaison supprimés sont déplacés dans la corbeille de recyclage où ils peuvent être consultés jusqu’à 30 jours mais ne peuvent pas être restaurés.