Sdílet prostřednictvím

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

  • Článek

Centrum rozhraní API vaší organizace zahrnuje integrované funkce lintingu spravované Microsoftem (Preview) k analýze definic rozhraní API pro dodržování pravidel organizačního stylu 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. Definice rozhraní API jsou ve výchozím nastavení lintovány pomocí sady pravidel spectral:oas (průvodce stylem rozhraní API).
  • Sestavy analýzy rozhraní API se generují na webu Azure Portal a ukazují, jak vaše definice rozhraní API odpovídají průvodci stylem.
  • Rozšíření Azure API Center pro Visual Studio Code můžete použít k místnímu přizpůsobení a otestování vlastního průvodce stylem rozhraní API a jeho nasazení do centra rozhraní API.

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.
  • V současné době nakonfigurujete jednu sadu pravidel a použije se u všech definic OpenAPI v centru rozhraní API.
  • Existuje omezení 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

Zobrazení souhrnu analýzy a sestav analýzy pro definice rozhraní API na webu Azure Portal 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 se sestavou analýzy rozhraní API na portálu

    Tip

    Sestavu analýzy rozhraní API můžete zobrazit také výběrem možnosti Analýza z řádku nabídek definice rozhraní API.

Přizpůsobení sady pravidel

Rozšíření Azure API Center pro Visual Studio Code můžete použít k přizpůsobení výchozí sady pravidel centra rozhraní API nebo jeho nahrazení jako průvodce stylem rozhraní API vaší organizace. Můžete například rozšířit sadu pravidel nebo přidat vlastní funkce.

Přizpůsobení nebo nahrazení sady pravidel:

  1. V editoru Visual Studio Code vyberte na panelu aktivit ikonu Centra rozhraní Azure API.
  2. .api-center-rules Otevřete složku v kořenovém adresáři pracovní složky.
  3. Ve složce prostředku centra rozhraní API otevřete ruleset.yml soubor.
  4. Podle potřeby upravte nebo nahraďte obsah.
  5. Uložte změny do ruleset.ymlsouboru .

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 stylem rozhraní API a stiskněte Enter.

  3. Zvolte Vybrat místní soubor a zadejte ruleset.yml 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 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 s lintováním definice rozhraní API v editoru 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. Klikněte pravým tlačítkem myši na Pravidla a vyberte Nasadit pravidla do centra rozhraní API.

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

Pokud chcete zobrazit výsledky lintování s aktualizovanou sadou pravidel, podívejte se na sestavy analýzy rozhraní API na portálu.

Související obsah