Un portail développeur qui ne peut pas dériver de votre API.
Cela remplace la documentation d'API hébergée qui devient obsolète des semaines après le lancement. Montrez-lui votre spécification OpenAPI et vos dépôts SDK. Il analyse les points de terminaison, extrait de vrais extraits de code, et publie un site de référence sous votre domaine avec les mêmes en-tête et pied de page que votre site marketing. La référence est en aval de votre source, elle reste donc à jour.
Ce qu'il remplace
Un outil de documentation hébergé publie ce que quelqu'un a tapé. Ici la référence est générée depuis la spec et la source du SDK, si bien que la seule chose qu'une personne écrit, ce sont les guides.
Un outil de documentation hébergé | Giant Context | |
|---|---|---|
La référence d'API | Écrite à la main depuis la spec, et corrigée à la main quand la spec change. | Générée depuis votre spec OpenAPI et resynchronisée sur un horaire, avec l'état de synchronisation et un journal d'événements quand une exécution échoue. |
Exemples de code | Collés, et décalés du SDK dès la deuxième version. | Extraits de vos dépôts SDK TypeScript et Python, associés à chaque point de terminaison, avec le fichier source et la ligne d'origine. |
Guides | Quiconque dans l'équipe a du temps ce trimestre. | L'IA les rédige dans la même voix que votre site marketing. Vous approuvez chacun. |
Où il vit | Un sous-domaine de documentation avec son propre en-tête, sa propre marque et sa propre connexion. | Votre domaine, avec les mêmes en-tête et pied de page que votre site et votre base de connaissances. Les tarifs sont à un clic, toujours sur votre site. |
Questions des développeurs | Une boîte de support. | L'agent de chat répond à partir de la référence et des guides. |
Bac à sable en direct | ||
Une documentation en aval de la source de vérité
Les guides sont le seul contenu qu'un humain rédige. Les pages de référence sont générées, elles ne peuvent donc pas se désynchroniser de l'API réelle.
- Vous pointez
Vers votre spec et vos dépôts
Donnez-lui une URL de spécification OpenAPI et vos dépôts SDK TypeScript et Python dans les paramètres.
- Il analyse
Points de terminaison, schémas et méthodes
Il indexe chaque point de terminaison en groupes d'API par étiquette, extrait les paramètres et les schémas de réponse, et récupère les méthodes et signatures de la source de votre SDK.
- Il associe
Extraits aux points de terminaison
Les méthodes du SDK sont associées aux points de terminaison par méthode HTTP et chemin, et des exemples cURL sont générés à partir des définitions.
- Il reste à jour
Resynchronisé depuis la source
La référence d'API se resynchronise depuis votre spec sur un horaire, et les extraits SDK depuis vos dépôts, si bien qu'un nouveau point de terminaison ou une nouvelle méthode apparaît sans que personne n'édite la documentation.
De vrais extraits, tirés de vos dépôts
Chaque page de point de terminaison montre un exemple cURL et les extraits SDK associés côte à côte. Ces deux-ci sont illustratifs. Sur votre portail, le code est extrait de votre source, avec le fichier et la ligne d'origine.
cURL
curl https://api.yourcompany.com/v1/contacts \ -H "Authorization: Bearer $YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "email": "ada@example.com", "name": "Ada Lovelace" }'client.ts
import { YourApi } from "@yourcompany/sdk";
const api = new YourApi({ apiKey: process.env.YOUR_API_KEY });
const contact = await api.contacts.create({ email: "ada@example.com", name: "Ada Lovelace",});L'authentification de votre API, montrée aux développeurs
Configurez les méthodes que votre API accepte, et elles apparaissent dans la référence pour que les développeurs sachent exactement comment s'authentifier.
Clé d'API
La voie la plus simple, montrée dans la référence.
HTTP
Authentification Bearer ou Basic.
OAuth 2.0
Pour les portails nécessitant un accès délégué.
OpenID Connect
L'identité au-dessus d'OAuth, documentée pour les développeurs.
Où sont les limites
Si l'une d'elles est rédhibitoire, autant le savoir maintenant.
Montrez-lui votre spec et lisez la référence
Demandez un accès anticipé. Donnez au portail une spécification OpenAPI et un dépôt SDK, lancez une synchronisation, et parcourez un site de référence qui reflète votre API réelle, sous votre propre domaine.