Un portail développeur qui reste synchronisé avec votre API
L'application Developers est un site de documentation hébergé pour l'API de votre propre produit. Il comprend les pages de référence, le code SDK et les guides que vos utilisateurs lisent lorsqu'ils s'intègrent à vous. Ce n'est pas un générateur de docs statiques que vous mettez à jour à la main. Elle lit votre spécification OpenAPI et votre source SDK, en extrait les points de terminaison et le code, et publie un site de référence consultable sous votre domaine. Lorsque votre API change, la documentation change avec elle.
Ce qu'il publie
Des docs qui restent à jour
Les pages de référence ne sont pas une copie de votre API. Elles en découlent. Pointez l'application vers l'URL de votre spécification OpenAPI et elle analyse chaque point de terminaison, les organise en groupes par tag et extrait les paramètres et les schémas. Pointez-la vers vos dépôts SDK sur GitHub et elle les clone, lit la source et extrait les méthodes et les signatures, en faisant correspondre chacune au point de terminaison qu'elle appelle par méthode HTTP et chemin.
La spécification se synchronise toutes les heures. Les SDK se synchronisent quotidiennement. Vous pouvez déclencher une synchronisation manuellement depuis les paramètres quand vous ne voulez pas attendre. Publiez un nouveau point de terminaison et la référence le reflète dans l'heure. Ajoutez une méthode SDK et les extraits se mettent à jour dans la journée. Les guides sont la seule partie rédigée par un humain.
Il ressemble au reste de votre site
Le portail hérite de son en-tête, de son pied de page et de sa mise en page de votre application web, et il est publié sous votre propre domaine. Un développeur lisant votre référence API qui clique sur « Tarifs » ne tombe pas sur un autre outil avec un aspect différent. Il n'y a pas de marquage Giant Context sur le portail généré, sauf si vous l'activez. Chaque page est rendue côté serveur, avec un plan du site généré pour vous.
Vous indiquez à l'application les méthodes d'authentification prises en charge par votre API, comme Clé API, HTTP Bearer, Basic, OAuth 2.0 ou OpenID Connect, et elles s'affichent sur les pages de référence pour que les développeurs sachent comment se connecter.
Ce qu'il ne fait pas encore
Questions fréquemment posées
Questions fréquemment posées
L'application lit directement votre spécification OpenAPI et vos dépôts SDK. La spécification se synchronise toutes les heures, les SDK quotidiennement, et vous pouvez déclencher une synchronisation manuellement. Les pages de référence sont générées à partir de la source, elles ne s'écartent donc pas de votre véritable API.
TypeScript et Python, plus des exemples cURL générés à partir de vos points de terminaison. D'autres langages nécessiteraient de nouveaux parseurs.
Pas encore. Les points de terminaison sont documentés mais ne sont pas exécutables dans le navigateur. Un bac à sable interactif est sur la feuille de route.