Udostępnij za pośrednictwem

Analizowanie interfejsów API w centrum interfejsu API — zarządzane przez firmę Microsoft

  • Artykuł

Centrum interfejsów API organizacji obejmuje wbudowane funkcje linting zarządzane przez firmę Microsoft (wersja zapoznawcza) do analizowania definicji interfejsu API w celu zapewniania zgodności z regułami stylu organizacji, generując zarówno raporty indywidualne, jak i podsumowania. Analiza interfejsu API identyfikuje i pomaga w usuwaniu typowych błędów i niespójności w definicjach interfejsu API.

Analiza interfejsu API:

  • Centrum interfejsów API platformy Azure automatycznie analizuje definicje interfejsu API za każdym razem, gdy dodasz lub zaktualizujesz definicję interfejsu API. Definicje interfejsu API są domyślnie linted za pomocą zestawu reguł spectral:oas (przewodnik po stylu interfejsu API).
  • Raporty analizy interfejsu API są generowane w witrynie Azure Portal, pokazując, jak definicje interfejsu API są zgodne z przewodnikiem stylu.
  • Możesz użyć rozszerzenia Azure API Center dla programu Visual Studio Code, aby dostosować i przetestować własny przewodnik stylu interfejsu API lokalnie, a następnie wdrożyć go w centrum interfejsu API.

Ważne

Jeśli wolisz, możesz włączyć samozarządzane linting i analizę przy użyciu niestandardowej funkcji platformy Azure, przesłaniając wbudowane funkcje. Wyłącz dowolną funkcję używaną do samodzielnego tworzenia lintingu przed użyciem analizy zarządzanego interfejsu API.

Ograniczenia

  • Obecnie analizowane są tylko dokumenty specyfikacji OpenAPI i AsyncAPI w formacie JSON lub YAML.
  • Obecnie konfigurujesz pojedynczy zestaw reguł i jest on stosowany do wszystkich definicji interfejsu OpenAPI w centrum interfejsu API.
  • Istnieją limity dla maksymalnej liczby analizowanych definicji interfejsu API. Ukończenie analizy może potrwać do 24 godzin.

Wymagania wstępne

Wyświetlanie raportów analizy interfejsu API

Wyświetlanie podsumowania analizy i raportów analizy definicji interfejsu API w witrynie Azure Portal. Po przeanalizowaniu definicji interfejsu API raporty zawierają listę błędów, ostrzeżeń i informacji na podstawie skonfigurowanego przewodnika po stylu interfejsu API.

W raporcie analizy interfejsu API zapoznaj się również z zestawem reguł używanym do analizy i historią przebiegów lintingu.

Aby wyświetlić podsumowanie analizy w centrum interfejsu API:

  1. W portalu przejdź do centrum interfejsu API.

  2. W menu po lewej stronie w obszarze Ład wybierz pozycję Analiza interfejsu API. Zostanie wyświetlone podsumowanie.

    Zrzut ekranu przedstawiający podsumowanie analizy interfejsu API w portalu.

  3. Opcjonalnie wybierz ikonę Raportu analizy interfejsu API dla definicji interfejsu API. Zostanie wyświetlony raport analizy interfejsu API definicji, jak pokazano na poniższym zrzucie ekranu.

    Zrzut ekranu przedstawiający raport analizy interfejsu API w portalu.

    Napiwek

    Raport analizy interfejsu API można również wyświetlić, wybierając pozycję Analiza na pasku menu definicji interfejsu API.

Dostosowywanie zestawu reguł

Możesz użyć rozszerzenia Centrum interfejsu API platformy Azure dla programu Visual Studio Code, aby dostosować domyślny zestaw reguł dla centrum interfejsu API lub zastąpić go jako przewodnik po stylu interfejsu API organizacji. Można na przykład rozszerzyć zestaw reguł lub dodać funkcje niestandardowe.

Aby dostosować lub zamienić zestaw reguł:

  1. W programie Visual Studio Code wybierz ikonę Centrum interfejsu API platformy Azure na pasku działań.
  2. .api-center-rules Otwórz folder w folderze głównym folderu roboczego.
  3. W folderze zasobu centrum interfejsu ruleset.yml API otwórz plik.
  4. Zmodyfikuj lub zastąp zawartość zgodnie z potrzebami.
  5. Zapisz zmiany w pliku ruleset.yml.

Lokalne testowanie zestawu reguł

Przed wdrożeniem niestandardowego zestawu reguł w centrum interfejsu API zweryfikuj go lokalnie. Rozszerzenie Centrum interfejsu API platformy Azure dla programu Visual Studio Code zapewnia zintegrowaną obsługę lintingu specyfikacji interfejsu API z funkcją Spectral.

  1. W programie Visual Studio Code użyj skrótu klawiaturowego Ctrl+Shift+P , aby otworzyć paletę poleceń.

  2. Wpisz Centrum interfejsów API platformy Azure: ustaw aktywny przewodnik stylu interfejsu API i naciśnij Enter.

  3. Wybierz pozycję Wybierz plik lokalny i określ ruleset.yml dostosowany plik. Naciśnij Enter.

    Ten krok sprawia, że niestandardowy zestaw reguł jest aktywnym przewodnikiem po stylu interfejsu API na potrzeby lintingu.

Teraz po otwarciu pliku definicji interfejsu API opartego na interfejsie OpenAPI lokalna operacja lintingu jest automatycznie wyzwalana w programie Visual Studio Code. Wyniki są wyświetlane w tekście w edytorze i w oknie Problemy (Wyświetl > problemy lub Ctrl+Shift+M).

Napiwek

Deweloperzy interfejsów API w organizacji mogą również używać tej lokalnej funkcji lintingu, aby ułatwić ulepszanie definicji interfejsu API przed zarejestrowaniem interfejsów API w centrum interfejsu API.

Zrzut ekranu przedstawiający tworzenie lintingu definicji interfejsu API w programie Visual Studio Code.

Przejrzyj wyniki lintingu. Wprowadź wszelkie niezbędne zmiany w zestawie reguł i kontynuuj testowanie go lokalnie, dopóki nie będzie działać zgodnie z potrzebami.

Wdrażanie zestawu reguł w centrum interfejsu API

Aby wdrożyć niestandardowy zestaw reguł w centrum interfejsu API:

  1. W programie Visual Studio Code wybierz ikonę Centrum interfejsu API platformy Azure na pasku działań.
  2. W okienku Centrum interfejsów API rozwiń zasób centrum interfejsu API, w którym dostosowano zestaw reguł.
  3. Kliknij prawym przyciskiem myszy pozycję Reguły i wybierz polecenie Wdróż reguły w Centrum interfejsu API.

Komunikat powiadamia Użytkownika po pomyślnym wdrożeniu reguł w centrum interfejsu API. Aparat linting używa zaktualizowanego zestawu reguł do analizowania definicji interfejsu API.

Aby wyświetlić wyniki lintingu ze zaktualizowanym zestawem reguł, wyświetl raporty analizy interfejsu API w portalu.

Powiązana zawartość