Erstellen und Registrieren von APIs mit der Azure API Center-Erweiterung für Visual Studio Code
API-Entwickler in Ihrer Organisation können APIs in Ihrem API Center-Bestand erstellen und registrieren, indem sie die Azure API Center-Erweiterung für Visual Studio Code verwenden. API-Entwickler können:
- Einem API-Center eine vorhandene API einmalig hinzufügen oder eine Entwicklungspipeline integrieren, um APIs als Teil eines CI/CD-Workflows zu registrieren.
- Verwenden Sie GitHub Copilot, um neue OpenAPI-Spezifikationen aus API-Code zu generieren.
- Verwenden Sie Anweisungen in natürlicher Sprache mit dem API Center-Plug-In für GitHub Copilot für Azure, um neue OpenAPI-Spezifikationen zu erstellen.
API-Entwickler können auch Features in der Erweiterung nutzen, um APIs im API Center zu entdecken und zu nutzen und API-Governance sicherzustellen.
Voraussetzungen
Ein oder mehrere API-Center in Ihrem Azure-Abonnement.
- Derzeit muss Ihnen die Rolle „Mitwirkender“ oder eine höhere Berechtigung für das Verwalten von APIs mit der Erweiterung zugewiesen werden.
Die folgenden Visual Studio Code-Erweiterungen sind für die angegebenen Szenarien erforderlich:
- GitHub Actions – zum Registrieren von APIs mithilfe einer CI/CD-Pipeline mit GitHub Actions
- Azure Pipelines – zum Registrieren von APIs mithilfe einer CI/CD-Pipeline mit Azure Pipelines
- GitHub Copilot – zum Generieren von OpenAPI-Spezifikationsdateien aus API-Code
- GitHub Copilot für Azure – zum Generieren von OpenAPI-Spezifikationsdateien mithilfe des Azure API Center-Plug-Ins für GitHub Copilot für Azure
Setup
Installieren Sie die Azure API-Center-Erweiterung für Visual Studio Code aus dem Visual Studio Code Marketplace. Installieren Sie nach Bedarf weitere Erweiterungen.
Hinweis
Sofern angegeben, stehen bestimmte Features nur in der Vorabversion der Azure API Center-Erweiterung zur Verfügung. Wenn Sie die Erweiterung aus dem Visual Studio Code Marketplace installieren, können Sie die endgültige Produktversion oder eine Vorabversion installieren. Wechseln Sie jederzeit zwischen den beiden Versionen, indem Sie das Kontextmenü der Erweiterungsschaltfläche Verwalten in der Erweiterungsansicht verwenden.
Wählen Sie in Visual Studio Code auf der Aktivitätsleiste auf der linken Seite „API-Center“ aus.
Wenn Sie nicht bei Ihrem Azure-Konto angemeldet sind, wählen Sie Bei Azure anmelden… aus, und folgen Sie den Anweisungen, um sich anzumelden. Wählen Sie ein Azure-Abonnement mit dem API Center (oder den API-Centern) aus, von dem bzw. denen Sie APIs anzeigen möchten. Sie können auch nach bestimmten Abonnements filtern, wenn viele zum Anzeigen verfügbar sind.
Registrieren einer API – Schritt für Schritt
Die folgenden Schritte registrieren eine API im API Center als einmaligen Vorgang.
- Verwenden Sie die Tastenkombination STRG+UMSCHALT+P, um die Befehlspalette zu öffnen. Geben Sie Azure API Center: Register API ein, und drücken Sie die Eingabetaste.
- Wählen Sie Manuell aus.
- Wählen Sie das API Center aus, bei dem APIs registriert werden sollen.
- Beantworten Sie die Eingabeaufforderungen mit Informationen wie API-Titel, Typ, Versionstitel, Versionslebenszyklus, Definitionstitel, Spezifikationsname und Definitionsdatei, um die API-Registrierung abzuschließen.
Die API wird Ihrem API Center-Bestand hinzugefügt.
Registrieren von APIs – CI/CD-Pipeline
Die folgenden Schritte registrieren eine API im API Center mit einer CI/CD-Pipeline. Fügen Sie mit dieser Option eine vorkonfigurierte GitHub- oder Azure DevOps-Pipeline zu Ihrem aktiven Visual Studio Code-Arbeitsbereich hinzu, der als Teil eines CI/CD-Workflows für jeden Commit zur Quellcodeverwaltung ausgeführt wird. Es wird empfohlen, APIs mit Ihrem API-Center mithilfe von CI/CD zu inventarisieren, um sicherzustellen, dass API-Metadaten, einschließlich Spezifikation und Version, im API-Center auf dem neuesten Stand bleiben, während die API im Laufe der Zeit weiterentwickelt wird.
- Verwenden Sie die Tastenkombination STRG+UMSCHALT+P, um die Befehlspalette zu öffnen. Geben Sie Azure API Center: Register API ein, und drücken Sie die Eingabetaste.
- Wählen Sie CI/CD aus.
- Wählen Sie entweder GitHub oder Azure DevOpsaus, je nachdem, welchen Mechanismus zur Quellcodeverwaltung Sie bevorzugen. Ein Visual Studio Code-Arbeitsbereich muss geöffnet sein, damit die Azure API-Center-Erweiterung Ihrem Arbeitsbereich eine Pipeline hinzufügen kann. Nachdem die Datei hinzugefügt wurde, führen Sie die Schritte aus, die in der CI/CD-Pipelinedatei selbst dokumentiert sind, um die erforderliche Umgebungsvariablen und Identitäten zu konfigurieren. Beim Push zur Quellcodeverwaltung wird die API in Ihrem API Center registriert.
Erfahren Sie mehr über das Einrichten eines GitHub Actions-Workflows zum Registrieren von APIs im API Center.
Generieren der OpenAPI-Spezifikation aus API-Code
Verwenden Sie die Leistungsfähigkeit von GitHub Copilot mit der Azure API Center-Erweiterung für Visual Studio Code, um eine OpenAPI-Spezifikationsdatei aus Ihrem API-Code zu erstellen. Klicken Sie mit der rechten Maustaste auf den API-Code, wählen Sie Copilot aus den Optionen aus, und wählen Sie API-Dokumentation generieren aus. GitHub Copilot erstellt eine OpenAPI-Spezifikationsdatei.
Hinweis
Diese Funktion ist in der Vorabversion der API Center-Erweiterung verfügbar.
Nach dem Generieren der OpenAPI-Spezifikationsdatei und der Überprüfung auf Genauigkeit können Sie die API für Ihr API Center mit dem Befehl Azure API Center: API registrieren registrieren.
Generieren der OpenAPI-Spezifikation mithilfe von Prompts in natürlicher Sprache
Das API Center-Plug-In für GitHub Copilot für Azure hilft Ihnen, neue APIs zu entwerfen, beginnend mit Prompts in natürlicher Sprache. Mit KI-Unterstützung generieren Sie schnell eine OpenAPI-Spezifikation für die API-Entwicklung, die den Standards Ihrer Organisation entspricht.
Hinweis
Diese Funktion ist in der Vorabversion der API Center-Erweiterung verfügbar.
Legen Sie bei Bedarf eine Anleitung für den aktiven API-Styleguide fest. Verwenden Sie die Tastenkombination STRG+UMSCHALT+P, um die Befehlspalette zu öffnen. Geben Sie Azure API Center: API-Styleguide festlegen ein, treffen Sie eine Auswahl und drücken Sie die EINGABETASTE.
Wenn kein Styleguide festgelegt ist, wird der Standardregelsatz
spectral:oasverwendet.Senden Sie im Chatbereich eine Anforderung in natürlicher Sprache an den
@azure-Agent, um zu beschreiben, was die API tut. Beispiel:@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.Der Agent antwortet mit einem OpenAPI-Spezifikationsdokument.
Überprüfen Sie die generierte Ausgabe auf Genauigkeit und Compliance mit Ihrem API-Styleguide. Verfeinern Sie den Prompt, falls erforderlich, um neu zu generieren.
Tipp
Effektive Prompts konzentrieren sich nicht auf Implementierungsdetails, sondern auf die Geschäftsanforderungen einer API. Kürzere Prompts funktionieren manchmal besser als längere.
Wenn sie Ihre Anforderungen erfüllt, speichern Sie die generierte OpenAPI-Spezifikation in einer Datei.
Registrieren Sie die API mit Ihrem API Center. Wählen Sie die Schaltfläche API im API Center registrieren im Chatbereich aus, oder wählen Sie Azure API Center: API registrieren in der Befehlspalette aus, und befolgen Sie die Anweisungen.