Aan de slag met de Azure API Center-extensie voor Visual Studio Code (preview)
Als u API's in uw API-centrum wilt bouwen, ontdekken, uitproberen en gebruiken, kunt u de Azure API Center-extensie gebruiken in uw Ontwikkelomgeving van Visual Studio Code:
API's bouwen: maak API's die u voor anderen maakt, detecteerbaar door ze te registreren in uw API-centrum. Shift-left API-ontwerpcontroles in Visual Studio Code met geïntegreerde linting-ondersteuning. Zorg ervoor dat nieuwe API-versies API-gebruikers niet breken met wijzigingsdetectie die fouten veroorzaken.
ONTDEK API's : blader door de API's in uw API-centrum en bekijk de bijbehorende details en documentatie.
PROBEER API's - Gebruik Swagger UI of REST-client om API-aanvragen en -antwoorden te verkennen.
API's gebruiken: API SDK-clients genereren voor uw favoriete taal, waaronder JavaScript, TypeScript, .NET, Python en Java, met behulp van de Microsoft Kiota-engine waarmee SDK's voor Microsoft Graph, GitHub en meer worden gegenereerd.
Notitie
De Azure API Center-extensie voor Visual Studio Code is in preview. Meer informatie over de preview-versie van de extensie.
Vereisten
Een of meer API-centra in uw Azure-abonnement. Als u er nog geen hebt gemaakt, raadpleegt u quickstart: Uw API-centrum maken.
Op dit moment moet u de rol Inzender of hogere machtigingen krijgen om toegang te krijgen tot API-centra met de extensie.
De volgende Visual Studio Code-extensies zijn optioneel en zijn alleen nodig voor bepaalde scenario's, zoals aangegeven:
- REST-clientextensie : http-aanvragen verzenden en de antwoorden rechtstreeks in Visual Studio Code weergeven
- Microsoft Kiota-extensie : API-clients genereren
- Spectral-extensie : om conformancecontroles voor api-ontwerp shift-left uit te voeren in Visual Studio Code
- Optic CLI : om belangrijke wijzigingen tussen API-specificatiedocumenten te detecteren
Instellingen
- Installeer de Azure API Center-extensie voor Visual Studio Code vanuit Visual Studio Code Marketplace. Installeer indien nodig optionele extensies.
- Selecteer API Center in Visual Studio Code in de activiteitenbalk aan de linkerkant.
- Als u niet bent aangemeld bij uw Azure-account, selecteert u Aanmelden bij Azure...en volgt u de aanwijzingen om u aan te melden. Selecteer een Azure-account met het API-centrum (of API-centra) waaruit u API's wilt weergeven. U kunt ook filteren op specifieke abonnementen als u er veel van kunt bekijken.
API's registreren
Registreer een API rechtstreeks vanuit Visual Studio Code in uw API-centrum door deze te registreren als eenmalige bewerking of met een CI/CD-pijplijn.
- Gebruik de sneltoets Ctrl+Shift+P om het opdrachtenpalet te openen. Typ Azure API Center: registreer de API en druk op Enter.
- Selecteer hoe u uw API wilt registreren bij uw API-centrum:
- Stapsgewijze instructies zijn het meest geschikt voor eenmalige registratie van API's.
- CI/CD voegt een vooraf geconfigureerde GitHub- of Azure DevOps-pijplijn toe aan uw actieve Visual Studio Code-werkruimte die wordt uitgevoerd als onderdeel van een CI/CD-werkstroom op elke doorvoering naar broncodebeheer. Het wordt aanbevolen OM API's te inventariseren met uw API-centrum met behulp van CI/CD om ervoor te zorgen dat API-metagegevens, inclusief specificatie en versie, actueel blijven in uw API-centrum naarmate de API zich in de loop van de tijd blijft ontwikkelen.
- Voltooi de registratiestappen:
- Voor stapsgewijze instructies selecteert u het API-centrum voor het registreren van API's en antwoordprompts met informatie zoals API-titel, type, levenscyclusfase, versie en specificatie om de API-registratie te voltooien.
- Voor CI/CD selecteert u GitHub of Azure DevOps, afhankelijk van het bronbeheermechanisme van uw voorkeur. Er moet een Visual Studio Code-werkruimte zijn geopend voor de Azure API Center-extensie om een pijplijn aan uw werkruimte toe te voegen. Nadat het bestand is toegevoegd, voert u de stappen uit die worden beschreven in het CI/CD-pijplijnbestand zelf om omgevingsvariabelen en identiteiten voor Azure Pipeline/GitHub Action te configureren. Bij het pushen naar broncodebeheer wordt de API geregistreerd in uw API-centrum.
Api-ontwerpconformance
De Azure API Center-extensie voor Visual Studio Code biedt geïntegreerde ondersteuning voor API-specificatie linting met Spectral om ervoor te zorgen dat het ontwerp voldoet aan de organisatiestandaarden tijdens het bouwen van API's.
- Gebruik de sneltoets Ctrl+Shift+P om het opdrachtenpalet te openen. Type Azure API Center: Stel de actieve API-stijlgids in en druk op Enter.
- Selecteer een van de standaardregels die zijn opgegeven, of als uw organisatie al een stijlgids heeft, gebruikt u Lokaal bestand of externe invoer-URL selecteren om de actieve regelset in Visual Studio Code op te geven. Druk op Enter.
Zodra een actieve API-stijlgids is ingesteld, activeert het openen van een OpenAPI- of AsyncAPI-specificatiebestand een lokale lintingbewerking in Visual Studio Code. Resultaten worden zowel inline weergegeven in de editor als in het venster Problemen (Problemen weergeven>of Ctrl+Shift+M).
Detectie van wijzigingen die fouten veroorzaken
Wanneer u nieuwe versies van uw API introduceert, is het belangrijk om ervoor te zorgen dat wijzigingen die zijn geïntroduceerd, api-gebruikers niet breken in eerdere versies van uw API. De Azure API Center-extensie voor Visual Studio Code maakt dit eenvoudig met wijzigingsdetectie voor OpenAPI-specificatiedocumenten die worden aangedreven door Optic.
- Gebruik de sneltoets Ctrl+Shift+P om het opdrachtenpalet te openen. Typ Azure API Center: Detecteer belangrijke wijziging en druk op Enter.
- Selecteer het eerste API-specificatiedocument dat u wilt vergelijken. Geldige opties zijn API-specificaties die zijn gevonden in uw API-centrum, een lokaal bestand of de actieve editor in Visual Studio Code.
- Selecteer het tweede API-specificatiedocument dat u wilt vergelijken. Geldige opties zijn API-specificaties die zijn gevonden in uw API-centrum, een lokaal bestand of de actieve editor in Visual Studio Code.
Visual Studio Code opent een diff-weergave tussen de twee API-specificaties. Wijzigingen die fouten veroorzaken, worden zowel inline weergegeven in de editor als in het venster Problemen (Problemen weergeven>of Ctrl+Shift+M).
API's detecteren
Uw API Center-resources worden weergegeven in de structuurweergave aan de linkerkant. Vouw een API Center-resource uit om API's, versies, definities, omgevingen en implementaties te bekijken.
Zoek naar API's in een API Center met behulp van het zoekpictogram dat wordt weergegeven in het apis-structuurweergave-item .
API-documentatie weergeven
U kunt de documentatie voor een API-definitie in uw API-centrum bekijken en API-bewerkingen proberen. Deze functie is alleen beschikbaar voor op OpenAPI gebaseerde API's in uw API-centrum.
Vouw de structuurweergave van API Center uit om een API-definitie weer te geven.
Klik met de rechtermuisknop op de definitie en selecteer Open API-documentatie. Er wordt een nieuw tabblad weergegeven met de Swagger-gebruikersinterface voor de API-definitie.
Als u de API wilt proberen, selecteert u een eindpunt, selecteert u Uitproberen, voert u de vereiste parameters in en selecteert u Uitvoeren.
Notitie
Afhankelijk van de API moet u mogelijk autorisatiereferenties of een API-sleutel opgeven om de API uit te proberen.
HTTP-bestand genereren
U kunt een .http bestand weergeven op basis van de API-definitie in uw API-centrum. Als de REST-clientextensie is geïnstalleerd, kunt u de map aanvragen indienen vanuit de Visual Studio Code-editor. Deze functie is alleen beschikbaar voor op OpenAPI gebaseerde API's in uw API-centrum.
Vouw de structuurweergave van API Center uit om een API-definitie weer te geven.
Klik met de rechtermuisknop op de definitie en selecteer HTTP-bestand genereren. Er wordt een nieuw tabblad weergegeven dat een HTTP-document weergeeft dat is gevuld met de API-specificatie.
Als u een aanvraag wilt indienen, selecteert u een eindpunt en selecteert u Aanvraag verzenden.
Notitie
Afhankelijk van de API moet u mogelijk autorisatiereferenties of een API-sleutel opgeven om de aanvraag te doen.
API-client genereren
Gebruik de Microsoft Kiota-extensie om een API-client te genereren voor uw favoriete taal. Deze functie is alleen beschikbaar voor op OpenAPI gebaseerde API's in uw API-centrum.
- Vouw de structuurweergave van API Center uit om een API-definitie weer te geven.
- Klik met de rechtermuisknop op de definitie en selecteer API-client genereren. Het deelvenster Kiota OpenAPI Generator wordt weergegeven.
- Selecteer de API-eindpunten en HTTP-bewerkingen die u wilt opnemen in uw SDK's.
- Selecteer Api-client genereren.
Voer configuratiegegevens in over de SDK-naam, naamruimte en uitvoermap.
Selecteer de taal voor de gegenereerde SDK.
De client wordt gegenereerd.
Zie de Microsoft Kiota-extensie voor Visual Studio Code voor meer informatie over het gebruik van de Kiota-extensie.