Samouczek: rejestrowanie interfejsów API w spisie interfejsów API

W tym samouczku uruchom spis interfejsów API w centrum interfejsu API organizacji, rejestrując interfejsy API i przypisując metadane przy użyciu witryny Azure Portal.

Aby uzyskać podstawowe informacje o interfejsach API, wersjach interfejsów API, definicjach i innych jednostkach, które można spisać w centrum interfejsów API platformy Azure, zobacz Kluczowe pojęcia.

Z tego samouczka dowiesz się, jak używać portalu do wykonywania następujących problemów:

• Rejestrowanie co najmniej jednego interfejsu API
• Dodawanie wersji interfejsu API z definicją interfejsu API

Wymagania wstępne

• Centrum interfejsu API w ramach subskrypcji platformy Azure. Jeśli jeszcze go nie utworzono, zobacz Szybki start: tworzenie centrum interfejsu API.

• Co najmniej jeden interfejs API, który chcesz zarejestrować w centrum interfejsu API. Oto dwa przykłady z linkami do ich definicji interfejsu OpenAPI:

  • Swagger Petstore API
  • Interfejs API konferencji

• Ukończ poprzedni samouczek Definiowanie metadanych niestandardowych, aby zdefiniować niestandardowe metadane dla interfejsów API.

Rejestrowanie interfejsów API

Podczas rejestrowania (dodawania) interfejsu API w centrum interfejsu API rejestracja interfejsu API obejmuje następujące elementy:

• Tytuł (nazwa), typ i opis
• Wersja
• Opcjonalne linki do dokumentacji i kontaktów
• Zdefiniowane wbudowane i niestandardowe metadane

Po zarejestrowaniu interfejsu API można dodawać wersje i definicje do interfejsu API.

W poniższych krokach zarejestrowano dwa przykładowe interfejsy API: interfejs API programu Swagger Petstore i interfejs API konferencji (zobacz Wymagania wstępne). Jeśli wolisz, zarejestruj własne interfejsy API.

1. W portalu przejdź do centrum interfejsu API.

2. W menu po lewej stronie w obszarze Zasoby wybierz pozycję Interfejsy> API+ Zarejestruj interfejs API.

3. Na stronie Rejestrowanie interfejsu API dodaj następujące informacje dotyczące interfejsu API programu Swagger Petstore. Zobaczysz niestandardowe metadane biznesowe i publiczne zdefiniowane w poprzednim samouczku w dolnej części strony.

   Ustawienie	Wartość	Opis
   Tytuł interfejsu API	Wprowadź interfejs API magazynu petstore programu Swagger.	Nazwa wybrana dla interfejsu API.
   Identyfikator	Po wprowadzeniu poprzedniego tytułu centrum interfejsu API platformy Azure generuje ten identyfikator, który można zastąpić.	Nazwa zasobu platformy Azure dla interfejsu API.
   Typ interfejsu API	Wybierz pozycję REST z listy rozwijanej.	Typ interfejsu API.
   Podsumowanie	Opcjonalnie wprowadź podsumowanie.	Opis podsumowania interfejsu API.
   Opis	Opcjonalnie wprowadź opis.	Opis interfejsu API.
   Wersja
   Tytuł wersji	Wprowadź wybrany tytuł wersji, taki jak wersja 1.	Nazwa wybrana dla wersji interfejsu API.
   Identyfikacja wersji	Po wprowadzeniu poprzedniego tytułu centrum interfejsu API platformy Azure generuje ten identyfikator, który można zastąpić.	Nazwa zasobu platformy Azure dla wersji.
   Cykl życia wersji	Wybierz z listy rozwijanej, na przykład Testowanie lub Produkcja.	Etap cyklu życia wersji interfejsu API.
   Dokumentacja zewnętrzna	Opcjonalnie dodaj co najmniej jeden link do dokumentacji zewnętrznej.	Nazwa, opis i adres URL dokumentacji interfejsu API.
   Licencja	Opcjonalnie dodaj informacje o licencji.	Nazwa, adres URL i identyfikator licencji interfejsu API.
   Informacje o kontakcie	Opcjonalnie dodaj informacje dla co najmniej jednego kontaktu.	Nazwa, adres e-mail i adres URL kontaktu dla interfejsu API.
   Działalność biznesowa	Jeśli te metadane zostały dodane w poprzednim samouczku, dokonaj wyboru z listy rozwijanej, takiej jak Marketing.	Niestandardowe metadane identyfikujące jednostkę biznesową będącą właścicielem interfejsu API.
   Publiczne	Jeśli te metadane zostały dodane, zaznacz pole wyboru.	Niestandardowe metadane identyfikujące, czy interfejs API jest dostępny publicznie, czy tylko wewnętrzny.

   

4. Wybierz pozycję Utwórz. Interfejs API jest zarejestrowany.

5. Powtórz poprzednie trzy kroki, aby zarejestrować inny interfejs API, taki jak interfejs API konferencji.

Napiwek

Podczas rejestrowania interfejsu API w portalu można wybrać dowolny ze wstępnie zdefiniowanych typów interfejsów API lub wprowadzić inny wybrany typ.

Interfejsy API są wyświetlane na stronie interfejsów API w portalu. Po dodaniu dużej liczby interfejsów API do centrum interfejsu API użyj pola wyszukiwania i filtrów na tej stronie, aby znaleźć żądane interfejsy API.

Po zarejestrowaniu interfejsu API można wyświetlić lub edytować właściwości interfejsu API. Na stronie Interfejsy API wybierz interfejs API, aby wyświetlić strony do zarządzania rejestracją interfejsu API.

Dodawanie wersji interfejsu API

W całym cyklu życia interfejs API może mieć wiele wersji. Możesz dodać wersję do istniejącego interfejsu API w centrum interfejsu API, opcjonalnie z plikiem definicji lub plikami.

W tym miejscu dodasz wersję do jednego z interfejsów API:

1. W portalu przejdź do centrum interfejsu API.

2. W menu po lewej stronie wybierz pozycję Interfejsy API, a następnie wybierz interfejs API, na przykład Swagger Petstore.

3. Na stronie interfejsu API w obszarze Szczegóły wybierz pozycję Wersje>+ Dodaj wersję.

   

4. Na stronie Dodawanie wersji interfejsu API:

   1. Wprowadź lub wybierz następujące informacje:

      Ustawienie	Wartość	Opis
      Tytuł wersji	Wprowadź wybrany tytuł wersji, taki jak wersja 2.	Nazwa wybrana dla wersji interfejsu API.
      Identyfikacja wersji	Po wprowadzeniu poprzedniego tytułu centrum interfejsu API platformy Azure generuje ten identyfikator, który można zastąpić.	Nazwa zasobu platformy Azure dla wersji.
      Cykl życia wersji	Wybierz z listy rozwijanej, taką jak Produkcja.	Etap cyklu życia wersji interfejsu API.

   2. Wybierz pozycję Utwórz. Zostanie dodana wersja.

Dodawanie definicji do wersji

Zazwyczaj należy dodać definicję interfejsu API do wersji interfejsu API. Centrum interfejsów API platformy Azure obsługuje definicje w typowych formatach specyfikacji tekstu, takich jak OpenAPI 2 i 3 dla interfejsów API REST.

Aby dodać definicję interfejsu API do wersji:

1. Na stronie Wersje interfejsu API wybierz swoją wersję interfejsu API.

2. W menu po lewej stronie wersji interfejsu API w obszarze Szczegóły wybierz pozycję Definicje>+ Dodaj definicję.

3. Na stronie Dodawanie definicji :

   1. Wprowadź lub wybierz następujące informacje:

      Ustawienie	Wartość	Opis
      Stanowisko	Wprowadź wybrany tytuł, taki jak definicja w wersji 2.	Nazwa wybrana dla definicji interfejsu API.
      Identyfikator	Po wprowadzeniu poprzedniego tytułu centrum interfejsu API platformy Azure generuje ten identyfikator, który można zastąpić.	Nazwa zasobu platformy Azure dla definicji.
      Opis	Opcjonalnie wprowadź opis.	Opis definicji interfejsu API.
      Nazwa specyfikacji	W przypadku interfejsu API magazynu petstore wybierz pozycję OpenAPI.	Format specyfikacji interfejsu API.
      Wersja specyfikacji	Wprowadź wybrany identyfikator wersji, na przykład 3.0.	Wersja specyfikacji.
      Document	Przejdź do lokalnego pliku definicji dla interfejsu API magazynu petstore lub wprowadź adres URL. Przykładowy adres URL: https://raw.githubusercontent.com/swagger-api/swagger-petstore/refs/heads/master/src/main/resources/openapi.yaml	Plik definicji interfejsu API.

      

   2. Wybierz pozycję Utwórz. Definicja jest dodawana.

W tym samouczku przedstawiono sposób używania portalu do wykonywania następujących problemów:

• Rejestrowanie co najmniej jednego interfejsu API
• Dodawanie wersji interfejsu API z definicją interfejsu API

Podczas tworzenia spisu interfejsów API skorzystaj z zautomatyzowanych narzędzi do rejestrowania interfejsów API, takich jak rozszerzenie Centrum interfejsów API platformy Azure dla programu Visual Studio Code i interfejsu wiersza polecenia platformy Azure.

Następne kroki

Spis interfejsów API zaczyna kształtować się. Teraz możesz dodawać informacje o środowiskach interfejsu API i wdrożeniach.

Dodawanie środowisk i wdrożeń interfejsu API