Analýza rozhraní API v Centru rozhraní API – Spravovaná Microsoftem

Centrum rozhraní API vaší organizace obsahuje integrované možnosti lintování spravované společností Microsoft k analýze definic API z hlediska dodržování stylistických pravidel organizace a generování jednotlivých i souhrnných sestav. Analýza rozhraní API identifikuje a pomáhá opravit běžné chyby a nekonzistence v definicích rozhraní API.

Analýza rozhraní API:

  • Azure API Center automaticky analyzuje definice rozhraní API pokaždé, když přidáte nebo aktualizujete definici rozhraní API. Lintování definic rozhraní API se ve výchozím nastavení provádí pomocí sady pravidel (průvodce stylem rozhraní API spectral:oas).
  • Sestavy analýzy rozhraní API se generují na webu Azure Portal a ukazují, jak vaše definice rozhraní API odpovídají průvodci stylem.
  • Pomocí profilů analýzy můžete určit sadu pravidel a podmínky filtru pro analyzovaná rozhraní API. Přizpůsobte sadu pravidel profilu pomocí rozšíření Azure API Center pro Visual Studio Code.

Důležité

Pokud chcete, můžete povolit samoobslužné lintování a analýzu pomocí vlastní funkce Azure, která přepisuje integrované funkce. Před použitím analýzy spravovaného rozhraní API zakažte jakoukoli funkci použitou k vlastnímu lintování.

Omezení

  • V současné době se analyzují pouze dokumenty specifikace OpenAPI a AsyncAPI ve formátu JSON nebo YAML.
  • Existuje omezení počtu analytických profilů a maximálního počtu analyzovaných definic rozhraní API. Dokončení analýzy může trvat několik minut až 24 hodin.

Požadavky

Zobrazení sestav analýzy rozhraní API

Zobrazit souhrn analýz a zprávy analýz pro definice rozhraní API v Azure portálu. Po analýze definic rozhraní API jsou v sestavách uvedeny chyby, upozornění a informace na základě nakonfigurovaného průvodce stylem rozhraní API.

V sestavě analýzy rozhraní API zkontrolujte také sadu pravidel, která se použila k analýze, a historii průchodů lintováním.

Zobrazení souhrnu analýzy v centru rozhraní API:

  1. Na portálu přejděte do centra rozhraní API.

  2. V nabídce vlevo v části Zásady správného řízení vyberte Analýzu rozhraní API. Zobrazí se souhrn.

    Snímek obrazovky se souhrnem analýzy rozhraní API na portálu

  3. Volitelně vyberte ikonu sestavy analýzy rozhraní API pro definici rozhraní API. Zobrazí se sestava analýzy rozhraní API definice, jak je znázorněno na následujícím snímku obrazovky.

    Snímek obrazovky zprávy o analýze rozhraní API na portálu

    Tip

    Sestavu analýzy rozhraní API můžete zobrazit také výběrem Analýza z menu definice rozhraní API.

Správa profilů analýzy

Azure API Center používá analyzační profily pro lintování a analýzu rozhraní API. Profil analýzy určuje sadu pravidel a volitelně filtruje podmínky pro analyzovaná rozhraní API. Výchozí profil analýzy použije spectral:oas sadu pravidel pro všechny definice OpenAPI a AsyncAPI.

Sadu pravidel můžete přizpůsobit a definovat podmínky filtru ve výchozím profilu nebo můžete vytvořit nový profil. Můžete například chtít použít jeden profil pro rozhraní API, která jsou ve vývoji, a jiný profil pro rozhraní API, která jsou v produkčním prostředí.

Poznámka:

Ve standardním plánu služby API Center můžete vytvořit až tři profily analýzy. V plánu Free se podporuje jenom jeden profil.

Vytvoření profilu analýzy:

  1. Na webu Azure Portal přejděte do centra rozhraní API.
  2. V nabídce vlevo v části Správa vyberte Analýza API>Spravovat profily analýzy>+ Vytvořit profil analýzy.
  3. V podokně Vytvořit nový profil analýzy zadejte název a popis profilu.
  4. V sadě pravidel se zobrazí typ analyzátoru (linting engine) pro tuto sadu pravidel. V současné době se podporuje jenom Spectral.
  5. V části Definovat podmínky filtru přidejte jednu nebo více podmínek filtru pro definice rozhraní API, na které se profil použije.
  6. Vyberte Vytvořit.

Snímek obrazovky s vytvořením profilu analýzy na portálu

Profil je vytvořen a vytvoří se základ sady pravidel. Pokud chcete zobrazit aktuální sadu pravidel, vyberte profil a v místní nabídce (...) vyberte Zobrazit sadu pravidel.

Pokud chcete sadu pravidel přizpůsobit, pokračujte následujícími částmi.

Přizpůsobení sady pravidel profilu

Sadu pravidel profilu můžete přizpůsobit pomocí rozšíření Visual Studio Code pro Azure API Center. Po přizpůsobení sady pravidel a jeho místním otestování ji můžete nasadit zpět do centra rozhraní API.

  1. V editoru Visual Studio Code vyberte na panelu aktivit ikonu Centra rozhraní Azure API.
  2. V podokně Centrum rozhraní API rozbalte prostředek rozhraní API, se kterým pracujete, a rozbalte Profily.
  3. Rozbalte profil, který chcete upravit, a vyberte ruleset.yaml.
  4. Podle potřeby upravte nebo nahraďte obsah.
  5. Uložte změny do ruleset.yamlsouboru .

Místní testovací sada pravidel

Před nasazením vlastní sady pravidel do centra rozhraní API ji ověřte místně. Rozšíření Azure API Center pro Visual Studio Code poskytuje integrovanou podporu pro lintování specifikace rozhraní API s využitím funkce Spectral.

  1. V editoru Visual Studio Code otevřete paletu příkazů pomocí klávesové zkratky Ctrl+Shift+P .

  2. Zadejte Azure API Center: Nastavte aktivní průvodce stylů API a stiskněte Enter.

  3. Zvolte Vybrat místní soubor a zadejte ruleset.yaml soubor, který jste přizpůsobili. Stiskněte Enter.

    Tento krok zpřístupňuje sadu vlastních pravidel jako aktivního průvodce stylem rozhraní API pro místní lintování.

Když teď otevřete definiční soubor rozhraní API založený na OpenAPI, automaticky se v editoru Visual Studio Code aktivuje místní operace lintování. Výsledky se zobrazí v editoru a v okně Problémy (Zobrazit > problémy nebo Ctrl+Shift+M).

Tip

Vývojáři rozhraní API ve vaší organizaci můžou tuto místní funkci lintování použít také k vylepšení definic rozhraní API před registrací rozhraní API ve vašem centru api.

Snímek obrazovky zobrazující lintování definice API ve Visual Studio Code

Zkontrolujte výsledky lintingu. Proveďte potřebné úpravy sady pravidel a pokračujte v jeho místním testování, dokud nebude fungovat požadovaným způsobem.

Nasazení sady pravidel do centra rozhraní API

Nasazení vlastní sady pravidel do centra rozhraní API:

  1. V editoru Visual Studio Code vyberte na panelu aktivit ikonu Centra rozhraní Azure API.
  2. V podokně Centrum rozhraní API rozbalte prostředek centra rozhraní API, ve kterém jste přizpůsobili sadu pravidel.
  3. Rozbalit profily
  4. Klikněte pravým tlačítkem na profil, ve kterém jste přizpůsobili sadu pravidel, a vyberte Nasadit pravidla do centra API Center.

Zpráva vás upozorní, jakmile se pravidla úspěšně nasadí do centra rozhraní API. Lintovací modul používá aktualizovanou sadu pravidel k analýze definic rozhraní API v profilu.

Chcete-li vidět výsledky analýzy lintování s aktualizovanou sadou pravidel, podívejte se na zprávy o analýze API na portálu.

Související obsah

  • Last updated on