L’URL pointe vers une adresse privée ou interne, ou redirige vers une telle adresse. Utilisez une adresse accessible à tous sur Internet.
Publier une référence d’API
Transformez votre spécification OpenAPI ou GraphQL en pages de référence d’API dans votre centre d’aide, avec un terrain de jeu où les lecteurs peuvent envoyer de vraies requêtes. Les lecteurs trouvent les opérations dans la même recherche que vos articles, et votre agent IA peut leur répondre à partir de ces informations.
Nécessite un abonnement actif ou une période d’essai.
Ajouter votre spécification
Dans Centre d’aide, ouvrez le menu d’ajout d’une section et choisissez Créer une référence d’API. Nous prenons en charge OpenAPI (JSON ou YAML), Swagger 2.0, GraphQL SDL et le JSON d’introspection GraphQL, jusqu’à 15 Mo. La source de la spécification détermine la manière dont elle est mise à jour :
Source | Mise à jour |
|---|---|
Depuis GitHub | Mise à jour lorsqu’un push modifie le fichier de spécification sur la branche choisie. Nécessite une connexion à GitHub. |
Depuis une URL | Nous la récupérons de nouveau toutes les six heures. L’introspection doit être activée sur un point de terminaison GraphQL. |
Importer un fichier | Jamais automatiquement. Importez un nouveau fichier avec Remplacer la spécification. |
Utilisez Actualiser maintenant pour récupérer immédiatement une URL ou une source GitHub, et Remplacer la spécification pour passer à une autre source. Pour documenter plusieurs versions d’une API, ajoutez une référence par version.
Personnaliser les pages
Tous les autres réglages se trouvent dans les paramètres de la référence : vous n’avez donc pas besoin de modifier la spécification.
Choisissez la présentation dans la barre latérale (à plat, sous forme de dossiers ou dans une seule entrée réduite), réorganisez les groupes et attribuez-leur des icônes.
Masquez les opérations, les schémas ou les types GraphQL dont les lecteurs n’ont pas besoin.
Modifiez le résumé d’une opération, ajoutez des notes ou des exemples de code personnalisés. Ces personnalisations sont conservées lors de l’actualisation de la spécification, tant que l’opération conserve sa méthode et son chemin.
Les exemples de code peuvent également provenir de la spécification elle-même : x-codeSamples, ainsi que des extraits de SDK dans les spécifications générées par Stainless.
Le terrain de jeu
Les lecteurs peuvent cliquer sur Essayer pour n’importe quelle opération, ou utiliser la page du terrain de jeu d’une référence GraphQL, puis envoyer une vraie requête. Les requêtes passent par nos serveurs plutôt que par le navigateur du lecteur ; votre API ne nécessite donc aucune configuration CORS. Elles ne peuvent atteindre que les serveurs répertoriés dans votre spécification, ou le point de terminaison GraphQL que vous avez défini, jamais des adresses privées ou internes. Les clés et les en-têtes saisis par les lecteurs sont envoyés avec leur requête et ne sont jamais publiés avec la référence.
Publier et limiter l’accès
Publiez la référence pour l’afficher dans votre centre d’aide, ou activez Publier immédiatement lors de sa création. Dépublier la référence d’API la met hors ligne tout en conservant vos paramètres. Sa suppression efface définitivement ses pages.
Une référence hérite des règles d’accès de sa section. Pour la montrer uniquement à certains clients, placez-la dans une section réservée à leur groupe. Consultez Afficher du contenu à des lecteurs spécifiques.
Erreurs de source
Hôte de l’URL de la spécification d’API bloqué
Impossible de résoudre l’hôte de l’URL de la spécification d’API
Le nom de domaine n’existe pas. Vérifiez que l’URL ne contient pas de faute de frappe.
Seules les URL HTTP(S) de spécifications d’API sont autorisées, et l’URL ne doit pas contenir d’identifiants intégrés
Utilisez une adresse http:// ou https:// simple, sans nom d’utilisateur ni mot de passe.
Impossible de récupérer la spécification depuis votre hôte, ou trop de redirections
Votre serveur a renvoyé une erreur ou a redirigé la requête plus de cinq fois. Vérifiez que l’URL renvoie toujours directement la spécification.
L’URL n’a renvoyé ni document de spécification ni schéma GraphQL
Faites-la pointer vers un fichier OpenAPI, un fichier GraphQL SDL ou un point de terminaison GraphQL avec l’introspection activée.
La spécification d’API dépasse la limite de 15 Mo
Réduisez la taille de la spécification, par exemple en créant une référence par API.
Impossible de s’authentifier auprès de GitHub, ou la connexion GitHub ne peut pas lire ce dépôt
Reconnectez GitHub ou autorisez votre connexion GitHub à accéder à ce dépôt, puis cliquez sur Actualiser maintenant.
Le chemin GitHub doit pointer vers un fichier, ou le fichier est introuvable dans le dépôt GitHub
Vérifiez que le chemin pointe vers le fichier de spécification lui-même, et non vers un dossier, et que celui-ci existe sur la branche ou le commit choisi.
Échec du traitement
Nous n’avons pas pu lire la spécification. Corrigez-la et utilisez Remplacer la spécification pour réessayer.