API's analyseren in uw API-centrum - door Microsoft beheerd

Het API-centrum van uw organisatie bevat ingebouwde, door Microsoft beheerde lintingmogelijkheden (preview) voor het analyseren van API-definities voor naleving van organisatiestijlregels, waarbij zowel afzonderlijke als overzichtsrapporten worden gegenereerd. API-analyse identificeert en helpt u bij het corrigeren van veelvoorkomende fouten en inconsistenties in uw API-definities.

Met API-analyse:

• Azure API Center analyseert automatisch uw API-definities wanneer u een API-definitie toevoegt of bijwerkt. De linting voor uw API-definities wordt standaard uitgevoerd met een spectral:oas regelset (API-stijlgids).
• API-analyserapporten worden gegenereerd in Azure Portal, waarin wordt getoond hoe uw API-definities voldoen aan de stijlhandleiding.
• Gebruik analyseprofielen om de regelset en filtervoorwaarden op te geven voor de API's die worden geanalyseerd. Pas de regelset van een profiel aan met behulp van de Azure API Center-extensie voor Visual Studio Code.

Beperkingen

• Momenteel worden alleen OpenAPI- en AsyncAPI-specificatiedocumenten in JSON- of YAML-indeling geanalyseerd.
• Er zijn limieten voor het aantal analyseprofielen en het maximum aantal GEANALYSEERDE API-definities. Het kan enkele minuten tot 24 uur duren voordat de analyse is voltooid.

Vereisten

• Een API-centrum in uw Azure-abonnement. Als u er nog geen hebt, raadpleegt u quickstart: Uw API-centrum maken.
• Voor het aanpassen van de regelset, Visual Studio Code en de volgende Visual Studio Code-extensies:
  • Azure API Center-extensie voor Visual Studio Code
  • Spectral-extensie voor Visual Studio Code

API-analyserapporten weergeven

Bekijk een analyseoverzicht en de analyserapporten voor uw API-definities in Azure Portal. Nadat API-definities zijn geanalyseerd, worden in de rapporten fouten, waarschuwingen en informatie weergegeven op basis van de geconfigureerde API-stijlgids.

Bekijk in het API-analyserapport ook de regelset die is gebruikt voor de analyse en de geschiedenis van linting-passen.

Een analyseoverzicht weergeven in uw API-centrum:

1. Navigeer in de portal naar uw API-centrum.

2. Selecteer API-analyse in het linkermenu onder Governance. De samenvatting wordt weergegeven.

   

3. Selecteer desgewenst het pictogram api-analyserapport voor een API-definitie. Het API-analyserapport van de definitie wordt weergegeven, zoals wordt weergegeven in de volgende schermopname.

   

   Tip

   U kunt het API-analyserapport ook bekijken door Analyse te selecteren in de menubalk van de API-definitie.

Analyseprofielen beheren

Azure API Center maakt gebruik van analysis-profielen voor het linten en analyseren van API's. Een analyseprofiel bevat een regelset en optioneel filtervoorwaarden voor API's die worden geanalyseerd. Het standaardanalyseprofiel past de spectral:oas regelset toe op alle OpenAPI- en AsyncAPI-definities.

U kunt de regelset aanpassen en filtervoorwaarden definiëren in het standaardprofiel of u kunt een nieuw profiel maken. U kunt bijvoorbeeld één profiel gebruiken voor API's die in ontwikkeling zijn en een ander profiel voor API's die in productie zijn.

Een analyseprofiel maken:

1. Navigeer in Azure Portal naar uw API-centrum.
2. Selecteer in het menu aan de linkerkant onder Governance de optie API-analyse>Analyseprofielen beheren>+ Analyseprofiel maken.
3. Voer in het deelvenster Nieuw analyseprofiel maken een naam en beschrijving voor het profiel in.
4. In Ruleset wordt het analysetype (linting engine) voor de regelset weergegeven. Momenteel wordt alleen Spectral ondersteund.
5. Voeg onder Filtervoorwaarden definiëren een of meer filtervoorwaarden toe voor API-definities waarop het profiel wordt toegepast.
6. Kies Maken.

Het profiel wordt gemaakt en er wordt een regelset-sjabloon gemaakt. Als u de huidige regelset wilt weergeven, selecteert u het profiel en selecteert u in het contextmenu (...) de regelset weergeven.

Als u de regelset wilt aanpassen, gaat u verder met de volgende secties.

De regelset van het profiel aanpassen

Gebruik de Visual Studio Code-extensie voor Azure API Center om de regelset van een profiel aan te passen. Nadat u de regelset hebt aangepast en lokaal hebt getest, kunt u deze weer implementeren in uw API-centrum.

1. Selecteer in Visual Studio Code het pictogram Azure API Center op de activiteitenbalk.
2. Vouw in het deelvenster API Center de API Center-resource uit waarmee u werkt en vouw profielen uit.
3. Vouw het profiel uit dat u wilt wijzigen en selecteer ruleset.yaml.
4. Wijzig of vervang de inhoud indien nodig.
5. Sla uw wijzigingen op ruleset.yamlin .

Regelset lokaal testen

Voordat u de aangepaste regelset implementeert in uw API-centrum, valideert u deze lokaal. De Azure API Center-extensie voor Visual Studio Code biedt geïntegreerde ondersteuning voor API-specificatieplining met Spectral.

1. Gebruik in Visual Studio Code de sneltoets Ctrl+Shift+P om het opdrachtenpalet te openen.

2. Type Azure API Center: Stel de actieve API-stijlgids in en druk op Enter.

3. Kies Lokaal bestand selecteren en geef het ruleset.yaml bestand op dat u hebt aangepast. Druk op Enter.

   Met deze stap maakt u de aangepaste regelset de actieve API-stijlhandleiding voor lokale linting.

Wanneer u nu een op OpenAPI gebaseerd API-definitiebestand opent, wordt er automatisch een lokale linting-bewerking geactiveerd in Visual Studio Code. Resultaten worden inline weergegeven in de editor en in het venster Problemen (Bekijk > problemen of Ctrl+Shift+M).

Bekijk de linting-resultaten. Breng de benodigde aanpassingen aan de regelset aan en blijf deze lokaal testen totdat deze naar wens wordt uitgevoerd.

Regelset implementeren in uw API-centrum

De aangepaste regelset implementeren in uw API-centrum:

1. Selecteer in Visual Studio Code het pictogram Azure API Center op de activiteitenbalk.
2. Vouw in het deelvenster API Center de API Center-resource uit waarin u de regelset hebt aangepast.
3. Vouw profielen uit.
4. Klik met de rechtermuisknop op het profiel waarin u de regelset hebt aangepast en selecteer Regels implementeren in API Center.

Er wordt een bericht weergegeven nadat de regels zijn geïmplementeerd in uw API-centrum. De linting-engine maakt gebruik van de bijgewerkte regelset voor het analyseren van API-definities in het profiel.

Als u de resultaten van linting met de bijgewerkte regelset wilt bekijken, bekijkt u de API-analyserapporten in de portal.

Gerelateerde inhoud

• Zie de Spectral GitHub-opslagplaats voor meer informatie over de standaard ingebouwde regelset.
• API-analyse inschakelen in uw API-centrum - zelfbeheerd