Udostępnij za pośrednictwem

Włączanie analizy interfejsu API w centrum interfejsu API — zarządzane przez firmę Microsoft

  • Artykuł

W tym artykule wyjaśniono, jak włączyć analizę interfejsu API w Centrum interfejsu API platformy Azure bez konieczności samodzielnego zarządzania nią (wersja zapoznawcza). Analiza interfejsu API oferuje funkcje lintingu umożliwiające analizowanie definicji interfejsu API w centrum interfejsu API organizacji. Linting gwarantuje, że definicje interfejsu API są zgodne z regułami stylu organizacji, generując raporty zarówno indywidualne, jak i podsumowania. Analiza interfejsu API umożliwia identyfikowanie i poprawianie typowych błędów i niespójności w definicjach interfejsu API.

Ważne

Analiza zarządzanego interfejsu API w usłudze API Center konfiguruje aparat linting i niezbędne zależności automatycznie. Możesz również ręcznie włączyć linting i analizę przy użyciu niestandardowej funkcji platformy Azure. Wyłącz dowolną funkcję używaną do ręcznego lintingu przed włączeniem analizy zarządzanego interfejsu API.

W tym scenariuszu:

  1. Dodaj zestaw reguł lintingu (przewodnik po stylu interfejsu API) w centrum interfejsu API przy użyciu rozszerzenia programu Visual Studio Code dla centrum interfejsu API platformy Azure.
  2. Usługa Azure API Center automatycznie uruchamia linting podczas dodawania lub aktualizowania definicji interfejsu API. Wyzwalana jest również dla wszystkich definicji interfejsu API podczas wdrażania zestawu reguł w centrum interfejsu API.
  3. Przejrzyj raporty analizy interfejsu API w witrynie Azure Portal, aby zobaczyć, jak definicje interfejsu API są zgodne z przewodnikiem stylu.
  4. Opcjonalnie dostosuj zestaw reguł dla interfejsów API organizacji. Przetestuj niestandardowy zestaw reguł lokalnie przed wdrożeniem go w centrum interfejsu API.

Ograniczenia

  • Obecnie analizowane są tylko dokumenty specyfikacji OpenAPI w formacie JSON lub YAML.
  • Domyślnie można włączyć analizę za spectral:oas pomocą zestawu reguł. Aby dowiedzieć się więcej o wbudowanych regułach, zobacz repozytorium Spectral GitHub.
  • 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

Włączanie analizy interfejsu API przy użyciu programu Visual Studio Code

Aby włączyć analizę interfejsu API przy użyciu domyślnego zestawu reguł lintingu:

  1. W programie Visual Studio Code otwórz folder, który będzie używany do zarządzania zestawami reguł dla centrum interfejsów API platformy Azure.

  2. Wybierz ikonę Centrum interfejsu API platformy Azure na pasku działań.

  3. W okienku Centrum interfejsów API rozwiń zasób centrum interfejsu API, w którym chcesz włączyć analizę interfejsu API.

  4. Kliknij prawym przyciskiem myszy pozycję Reguły i wybierz pozycję Włącz analizę interfejsu API.

    Zrzut ekranu przedstawiający włączanie lintingu i analizy interfejsu API w programie Visual Studio Code.

Komunikat powiadamia o pomyślnym włączeniu analizy interfejsu API. Folder centrum interfejsu API jest tworzony w .api-center-rulesfolderze , w folderze głównym folderu roboczego. Folder centrum interfejsu API zawiera następujące elementy:

  • ruleset.yml Plik, który definiuje domyślny przewodnik stylu interfejsu API używany przez aparat linting.
  • Folder functions z przykładową funkcją niestandardową, której można użyć do rozszerzenia zestawu reguł.

Po włączeniu analizy aparat linting analizuje definicje interfejsów API w centrum interfejsu API na podstawie domyślnego zestawu reguł i generuje raporty analizy interfejsu API.

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.

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ł

Domyślny zestaw reguł można dostosować 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 otwórz .api-center-rules folder w folderze głównym folderu roboczego.
  2. W folderze zasobu centrum interfejsu API otwórz ruleset.yml plik.
  3. Zmodyfikuj lub zastąp zawartość zgodnie z potrzebami.
  4. 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).

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ść