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 sélectionnez 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 JSON ou YAML OpenAPI, ainsi que les fichiers de schéma GraphQL portant l’extension .graphql, .gql ou .graphqls. Sélectionnez Importer un fichier, puis choisissez 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.
Sélectionnez 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.
Sélectionnez Depuis GitHub.
Sélectionnez une connexion GitHub. Si vous n’avez pas encore connecté GitHub, configurez-le d’abord dans l’intégration GitHub.
Sélectionnez le dépôt.
Vous pouvez également choisir une branche ou un commit. La branche de production configurée est utilisée lorsqu’elle est disponible ; sinon, la branche GitHub par défaut 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 soit réussie.
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 si vous souhaitez utiliser Publier immédiatement.
Cliquez sur Ajouter une référence d’API.
Le traitement prend généralement 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.
Étape suivante
Gardez la source à jour dans Remplacer une spécification de référence d’API et Actualiser les sources de référence d’API, puis personnalisez la barre latérale et les pages d’opération dans Personnaliser une référence d’API.