Créer une référence d’API
Créez une référence d’API dans votre centre d’aide à partir d’une spécification OpenAPI, Swagger 2.0, GraphQL SDL ou JSON d’introspection GraphQL. Vous pouvez importer un fichier, lire la spécification depuis un dépôt GitHub ou la récupérer depuis une URL. La création et la publication d’une référence d’API nécessitent un abonnement actif ou en période d’essai, et les fichiers de spécification doivent faire moins de 15 Mo.
Ajouter une référence d’API
Accédez à la page Centre d’aide dans le tableau de bord.
Dans l’en-tête d’une section, cliquez sur le bouton d’ajout de contenu, puis choisissez Créer une référence d’API.
Dans la boîte de dialogue Ajouter une référence d’API, choisissez une source : Importer un fichier, Depuis GitHub ou Depuis une URL.
Importer un fichier de spécification
L’importation accepte les fichiers OpenAPI JSON ou YAML, ainsi que les fichiers de schéma GraphQL portant l’extension .graphql, .gql ou .graphqls. Choisissez Importer un fichier, puis sélectionnez votre fichier de spécification.
Ajouter une spécification depuis une URL
Utilisez cette option lorsque votre spécification est déjà hébergée en ligne. L’URL peut pointer vers un document OpenAPI, un fichier GraphQL SDL ou un endpoint GraphQL.
Choisissez Depuis une URL.
Saisissez l’URL de votre spécification ou de votre endpoint GraphQL.
L’introspection doit être activée pour les endpoints GraphQL. Les sources URL sont automatiquement actualisées toutes les six heures.
Si l’URL de votre spécification provient de Stainless, les pages générées peuvent afficher des extraits de SDK.
Ajouter une spécification depuis GitHub
Lisez directement le fichier de spécification depuis un dépôt à chaque synchronisation. La connexion GitHub doit appartenir au même espace de travail et avoir accès au dépôt.
Choisissez Depuis GitHub.
Sélectionnez une connexion GitHub. Si vous n’avez pas encore connecté GitHub, commencez par le faire dans l’intégration GitHub.
Sélectionnez le dépôt.
Vous pouvez choisir une branche ou un commit. La branche de production configurée est utilisée lorsqu’elle est disponible ; sinon, la branche par défaut GitHub du dépôt est utilisée.
Saisissez le chemin relatif au dépôt vers le fichier de spécification.
Cliquez sur Vérifier la spécification et attendez que la vérification réussisse.
La vérification de la spécification doit réussir avant que vous puissiez créer la référence d’API depuis GitHub.
Configurer et créer
Saisissez un slug d’URL pour la référence.
Choisissez d’utiliser ou non Publier immédiatement.
Cliquez sur Ajouter une référence d’API.
Le traitement ne prend généralement que quelques secondes. Lorsque la spécification est prête, le message Votre référence d’API est prête s’affiche ; cliquez sur Terminé pour terminer. Si le traitement échoue, le message Échec du traitement s’affiche ; cliquez sur Fermer pour fermer la boîte de dialogue.
SDK et exemples de code sur les pages d’opérations
Les pages d’opérations générées affichent des exemples de code provenant de trois sources, dans cet ordre : les exemples déclarés dans la spécification avec l’extension x-codeSamples, les extraits de SDK fournis dans l’extension x-stainless-snippets (que les spécifications générées par Stainless incluent, dans des langages tels que TypeScript, Python, Go, Java et Ruby), puis les exemples générés dans des langages courants tels que cURL, JavaScript, Python, Go et Ruby.
Ferndesk ne gère pas de correspondance entre les endpoints REST et les méthodes du SDK : les exemples de SDK affichés aux lecteurs sont ceux contenus dans votre spécification. Pour ajouter des exemples rédigés manuellement pour chaque opération, utilisez Exemples de code personnalisés dans Remplacer les détails d’une opération.
Versions de l’API
Chaque référence d’API suit une version de spécification, affichée dans la vue d’ensemble de la référence. Pour documenter plusieurs versions d’une API, créez une référence distincte pour chaque version, chacune avec sa propre source ; les références ne sont pas regroupées comme différentes versions d’une même API.
Et ensuite
Actualisez la source dans Remplacer la spécification d’une référence d’API et Actualiser les sources des références d’API, puis ajustez la barre latérale et les pages d’opérations dans Personnaliser une référence d’API.