Utiliser l' assistant API pour documenter vos API

Vous pouvez utiliser le composant d'amélioration des spécifications de l' assistant API pour vous aider à améliorer votre documentation API en analysant votre définition de l'API et en générant des recommandations pour vos descriptions et vos exemples. L'amélioration de la spécification de votre API accélère son adoption par les consommateurs.

Le composant d'amélioration des spécifications utilise le IBM watsonx Granite LLM models pour vous aider à créer vos API plus rapidement. Profitez de l' assistant API pour générer rapidement des descriptions et des exemples clairs et concis afin de documenter vos définitions d'API.

Comment utiliser l' assistant API pour générer des exemples et des descriptions pour votre API?

Vous utilisez l' assistant API lors de la création ou de la modification d'une définition d'API dans l'interface utilisateur du gestionnaire d'API. L' assistant API examine la définition de l'API et propose des descriptions et des exemples pour les champs du schéma. Vous pouvez ensuite choisir les suggestions que vous souhaitez que API Connect intègre dans votre définition de l'API.

  1. Connectez-vous à API Connect Enterprise as a Service en utilisant un Premium subscription.
  2. Dans API Manager, ouvrez une OpenAPI 3.0 API que vous souhaitez modifier.
  3. Dans l'onglet Conception, cliquez sur l'icône de l'affichage de la source (qui est un petit carré gris contenant deux crochets d'angle qui entourent une barre oblique) pour travailler dans la vue Source.
  4. Cliquez sur l'icône AI (qui est un petit carré gris contenant les lettres AI et une flèche en noir) pour ouvrir le panneau API Assistant.
  5. Assurez-vous que le panneau Specification enhancements est ouvert, et cliquez sur Generate pour demander des suggestions d'IA pour la description de l'API et les exemples.
  6. Cliquez sur Apply pour chaque suggestion que vous souhaitez incorporer dans votre API.

    Pour accepter rapidement toutes les suggestions, cliquez sur Appliquer tout.

  7. Cliquez sur Save pour enregistrer la définition de l'API mise à jour.

Exemple : Amélioration de l'API de l'échantillon EmployeesApi

Dans cet exemple, nous utilisons une EmployeesApi pour montrer le processus de génération de suggestions d'IA, d'examen des suggestions et d'application à l'API. Vous pouvez suivre les étapes avec votre propre API.

  1. Connectez-vous à API Connect Enterprise as a Service en utilisant un Premium subscription.

  2. Dans API Manager, cliquez sur l'icône Développer (qui est un petit carré noir contenant un crayon blanc) Develop pour ouvrir la page de développement de l'API, puis assurez-vous que l'onglet APIs est sélectionné afin de pouvoir visualiser vos API.
    Ouvrir la page Développer

  3. Sélectionnez une API de Type OpenAPI 3.0 (REST), et cliquez sur son Titre pour la modifier.
    Modifier une OpenAPI 3.0 API

  4. La page Conception s'ouvre en vue Formulaire.

    Notez que l'exemple d'API ne contient pas de descriptions pour certaines propriétés.

    Il manque des descriptions de propriétés dans l'exemple d'API

  5. Cliquez sur l'icône de l'affichage de la source (qui est un petit carré gris contenant deux crochets d'angle qui entourent une barre oblique) pour travailler dans la vue Source.

    L' assistant API est plus facile à utiliser lorsque vous pouvez voir le code source de votre API.

    Utilisez la vue Source pour voir le code de l'API
  6. Cliquez sur l'icône AI (qui est un petit carré gris contenant les lettres AI et une flèche en noir) pour ouvrir le panneau API Assistant. Assurez-vous que l'onglet Améliorations des spécifications est sélectionné.
  7. Dans le panneau Améliorations des spécifications, vous pouvez cliquer sur l'icône AI expliquée (qui est le contour d'un petit carré noir contenant les lettres AI) pour en savoir plus sur la façon dont l' assistant API utilise l'IA pour améliorer vos définitions d'API.
    En savoir plus sur l'assistant API

    Cliquez à nouveau sur l'icône AI expliquée (qui est le contour d'un petit carré noir contenant les lettres AI) pour fermer la fenêtre contextuelle.

  8. Cliquez maintenant sur Générer pour voir si des suggestions d'IA sont recommandées pour votre API.

    Dans notre exemple d'API, l' assistant API analyse la définition de l'API et renvoie un texte suggéré pour toutes les descriptions et tous les exemples vides.

    Cliquez sur Générer et consultez les suggestions

    Remarquez les changements suivants à l'écran :

    • Le panneau de l' assistant API affiche le nom de chaque champ et la description ou l'exemple proposé. Les valeurs correspondantes sont également insérées et mises en évidence dans le code source de l'API afin que vous puissiez les voir en place.

      Lorsque le panneau Assistant API est ouvert, le code source de l'API est en mode lecture seule afin d'éviter les mises à jour accidentelles. Lorsque vous fermez le panneau, le code redevient modifiable.

    • Si une propriété contient déjà une description ou un exemple, la valeur existante est conservée. Par exemple, dans notre exemple d'API, la propriété employeeNumber contient déjà une description de test, de sorte qu'aucune suggestion n'est générée pour cette propriété.
    • Dans le menu Design, les icônes Proposition d'IA fournie et Icône Supprimer s'affichent pour toute section de la définition de l'API ayant reçu des suggestions, afin que vous puissiez facilement accéder à cette suggestion ou la supprimer.
  9. Lorsque vous êtes prêt à accepter ou à refuser les suggestions, prenez l'une des mesures suivantes :
    • Accepter toutes les suggestions :

      Cliquez sur Appliquer tout pour accepter rapidement toutes les suggestions.

    • Régénérer toutes les suggestions :

      Cliquez sur l'icône Régénérer tout pour régénérer toutes les suggestions qui n'ont pas encore été appliquées.

    • Accepter une suggestion :

      Cliquez sur Appliquer pour chaque suggestion que vous souhaitez accepter.

    • Supprimer une suggestion :

      Cliquez sur Icône Supprimer pour chaque suggestion que vous souhaitez supprimer.

    Au fur et à mesure que vous travaillez avec les suggestions, notez les comportements suivants :

    • Toutes les suggestions que vous appliquez sont ajoutées à la définition de l'API, mais la définition elle-même n'est pas enregistrée tant que vous n'avez pas cliqué sur Save dans l'en-tête de la page.
    • Lorsque vous cliquez sur Sauvegarder, vos propres modifications et toutes les suggestions appliquées sont sauvegardées ; toutefois, les suggestions que vous n'avez pas appliquées sont perdues.
    • Si vous quittez la page API Design avant d'appliquer une suggestion, celle-ci est perdue.
    • Vous pouvez à tout moment modifier à nouveau l'API et générer des suggestions pour les descriptions et les exemples vides.
  10. Cliquez sur Icône de fermeture pour fermer le panneau de l' assistant API.

  11. Revenez à la vue Form en cliquant sur l'icône d'affichage du formulaire (qui est un petit carré gris contenant le contour en noir d'une feuille de papier avec un crayon).

    Dans l'exemple d'API, vous pouvez voir que les champs Description pour les propriétés EmployeeBody contiennent maintenant les descriptions suggérées.

    Les suggestions appliquées sont ajoutées à la définition de l'API

  12. N'oubliez pas de cliquer sur Save pour enregistrer la définition de l'API mise à jour.