Générer et inscrire des API avec l’extension Centre API Azure pour Visual Studio Code

Les développeurs d’API de votre organisation peuvent générer et inscrire des API dans l’inventaire de votre centre d’API à l’aide de l’extension Centre d’API Azure pour Visual Studio Code. Les développeurs d’API peuvent :

• Ajouter une API existante à un centre d’API en tant qu’opération ponctuelle ou intégrer un pipeline de développement pour inscrire des API dans le cadre d’un flux de travail CI/CD.
• Utilisez GitHub Copilot pour générer de nouvelles spécifications OpenAPI à partir du code API.
• Utilisez des requêtes en langage naturel avec le plug-in Centre API pour GitHub Copilot pour Azure afin de créer des spécifications OpenAPI.

Les développeurs d’API peuvent également tirer parti des fonctionnalités de l’extension pour découvrir et consommer des API dans le centre d’API et garantir la gouvernance des API.

Prérequis

• Un ou plusieurs centres d’API dans votre abonnement Azure.

  • Actuellement, vous devez disposer du rôle de Contributeur au service Centre API d’Azure ou d’autorisations supérieures sur un centre API pour gérer des API avec l’extension.

• Visual Studio Code

• Extension Centre API Azure pour Visual Studio Code

Les extensions Visual Studio Code suivantes sont nécessaires pour les scénarios spécifiés :

• GitHub Actions : pour inscrire des API à l’aide d’un pipeline CI/CD avec GitHub Actions
• Azure Pipelines : pour inscrire des API à l’aide d’un pipeline CI/CD avec Azure Pipelines
• GitHub Copilot : pour générer des fichiers de spécification OpenAPI à partir du code API
• GitHub Copilot pour Azure : pour générer des fichiers de spécifications OpenAPI à l’aide du plug-in Centre API d’Azure pour GitHub Copilot pour Azure

Programme d’installation

1. Installez l’extension Centre API Azure pour Visual Studio Code à partir de la Place de marché Visual Studio Code. Installez d’autres extensions, le cas échéant.

   Remarque

   Lorsque cela est indiqué, certaines fonctionnalités sont disponibles uniquement dans la préversion de l’extension Azure API Center. Lors de l’installation de l’extension à partir de la Place de marché Visual Studio Code, vous pouvez choisir d’installer la version de mise en production ou une version préliminaire. Basculez entre les deux versions à tout moment à l’aide du menu contextuel Gérer du bouton Gérer de l’extension, dans la vue Extensions.

2. Dans Visual Studio Code, dans la barre d’activités à gauche, sélectionnez API Center (Centre API).

   

3. Si vous n’êtes pas connecté à votre compte Azure, sélectionnez Sign in to Azure... (Se connecter à Azure), puis suivez les invites pour vous connecter. Sélectionnez un abonnement Azure avec le ou les centres API à partir desquels vous souhaitez afficher des API. Vous pouvez également filtrer sur des abonnements spécifiques si vous en avez un grand nombre à voir.

Inscrire une API : étape par étape

Les étapes suivantes inscrivent une API dans votre centre d’API en tant qu’opération ponctuelle.

1. Utilisez le raccourci clavier Ctrl+Maj+P pour ouvrir la palette de commandes. Tapez Centre API Azure : inscrire une API et appuyez sur Entrée.
2. Sélectionnez Manuel.
3. Sélectionnez le centre d’API auquel vous souhaitez inscrire des API.
4. Les invites de réponse avec des informations incluant le titre, le type, le titre de version, le cycle de vie de la version, le titre de la définition, le nom de spécification et le fichier de définition de l’API pour terminer l’inscription de l’API.

L’API est ajoutée à l’inventaire de votre centre d’API.

Inscrire des API : pipeline CI/CD

Les étapes suivantes inscrivent une API dans votre centre d’API avec un pipeline CI/CD. Avec cette option, ajoutez un pipeline GitHub ou Azure DevOps préconfiguré à votre espace de travail Visual Studio Code actif qui s’exécute dans le cadre d’un flux de travail CI/CD à chaque validation du contrôle de code source. Il est recommandé d’inventorier les API dans le centre API à l’aide de la méthode CI/CD pour faire en sorte que les métadonnées d’API, notamment la spécification et la version, restent à jour dans votre centre API, à mesure que les API évoluent au fil du temps.

1. Utilisez le raccourci clavier Ctrl+Maj+P pour ouvrir la palette de commandes. Tapez Centre API Azure : inscrire une API et appuyez sur Entrée.
2. Sélectionnez CI/CD.
3. Sélectionnez GitHub ou Azure DevOps, en fonction du mécanisme de contrôle de code source que vous utilisez. Un espace de travail Visual Studio Code doit être ouvert pour que l’extension Centre d’API Azure puisse ajouter un pipeline à votre espace de travail. Une fois le fichier ajouté, effectuez les étapes décrites dans le fichier de pipeline CI/CD lui-même pour configurer l’identité et les variables d’environnement requises. Dès l’envoi (push) au contrôle de code source, l’API est inscrite dans votre centre d’API.

Apprenez-en davantage sur la configuration d’un flux de travail GitHub Actions pour inscrire des API auprès de votre centre API.

Générer des spécifications OpenAPI à partir du code d’API

Utilisez la puissance de GitHub Copilot avec l’extension Centre API d’Azure pour Visual Studio Code afin de créer un fichier de spécification OpenAPI à partir de votre code d’API. Cliquez avec le bouton droit sur le code API, sélectionnez Copilot dans les options, puis sélectionnez Générer la documentation de l’API. GitHub Copilot crée un fichier de spécification OpenAPI.

Remarque

Cette fonctionnalité est disponible dans la version préliminaire de l’extension du Centre d’API.

Après avoir généré le fichier de spécification OpenAPI et vérifié la précision, vous pouvez inscrire l’API auprès de votre centre d’API à l’aide de la commande Azure API Center : Inscrire l’API .

Générer des spécifications OpenAPI à l’aide de requêtes en langage naturel

Le plug-in Centre API pour GitHub Copilot pour Azure vous aide à concevoir de nouvelles API à partir de requêtes en langage naturel. Avec l’aide de l’IA, générez rapidement une spécification OpenAPI pour le développement d’API en conformité avec les normes de votre organisation.

Remarque

Cette fonctionnalité est disponible dans la version préliminaire de l’extension du Centre d’API.

1. Si vous le souhaitez, définissez un guide de style d’API actif. Utilisez le raccourci clavier Ctrl+Maj+P pour ouvrir la palette de commandes. Tapez Centre API d’Azure : Définir un guide de style d’API, faites votre sélection, puis appuyez sur Entrée.

   Si aucun guide de style n’est défini, l’ensemble de règles par défaut spectral:oas est utilisé.

2. Dans le panneau de conversation, faites une demande en langage naturel à l’agent @azure pour décrire ce que fait l’API. Exemple :

   @azure Generate OpenAPI spec: An API that allows customers to pay for an order using various payment methods such as cash, checks, credit cards, and debit cards.
   

   L’agent répond avec un document de spécification OpenAPI.

   

3. Passez en revue la sortie générée pour vérifier son exactitude et sa conformité avec votre guide de style d’API. Affinez la requête si nécessaire pour régénérer la sortie.

   Conseil

   Les requêtes efficaces se concentrent sur les exigences métier d’une API plutôt que sur les détails de l’implémentation. Des requêtes plus courtes fonctionnent parfois mieux que des requêtes plus longues.

4. Quand vous êtes satisfait du résultat, enregistrez la spécification OpenAPI générée dans un fichier.

5. Inscrivez l’API auprès de votre Centre API. Sélectionnez le bouton Inscrire votre API dans le Centre API dans le panneau de conversation ou sélectionnez Centre API d’Azure : Inscrire l’API à partir de la palette de commandes, puis suivez les invites.

Contenu connexe

• Centre API Azure : les concepts clés
• Découvrir et consommer des API avec l’extension Centre d’API Azure pour Visual Studio Code
• Gérer des API avec l’extension Centre d’API Azure pour Visual Studio Code
• Activer et afficher le catalogue d’API de plateforme dans Visual Studio Code