Opublikuj swoje interfejsy API (wersja oryginalna)

Wyświetlasz dokumentację Apigee Edge.
Otwórz dokumentację Apigee X. info

Opublikuj interfejsy API w portalu, aby udostępnić je programistom aplikacji (zgodnie z opisem w kolejnych sekcjach).

Omówienie publikowania interfejsów API

Proces publikowania interfejsów API w portalu składa się z 2 etapów:

1. Wybierz usługę API, którą chcesz opublikować w portalu.
2. Automatyczne generowanie dokumentacji API na podstawie zrzutu specyfikacji OpenAPI, aby deweloperzy aplikacji mogli dowiedzieć się więcej o interfejsach API. (Więcej informacji o zrzutach znajdziesz w artykule Czym jest zrzut specyfikacji OpenAPI?

Gdy opublikujesz interfejs API w portalu, automatycznie zostaną w nim wprowadzone te zmiany:

• Do portalu zostanie dodana strona z dokumentacją interfejsu API
  Na stronie z dokumentacją interfejsu API wyświetlana jest dokumentacja interfejsu API, która jest generowana automatycznie na podstawie migawki specyfikacji OpenAPI. Programiści mogą przejrzeć dokumentację API i kliknąć Wypróbuj, aby wysłać żądanie do interfejsu API i wyświetlić dane wyjściowe.

  Uwaga: nie możesz bezpośrednio edytować zawartości tej strony. Nie pojawia się ona na liście stron w portalu.

  

• Na stronie interfejsów API dodano link do strony dokumentacji API
  Strona interfejsów API (dołączona do przykładowego portalu) zawiera listę wszystkich interfejsów API opublikowanych w portalu wraz z linkami do odpowiedniej dokumentacji API, w której znajdziesz więcej informacji.

  Uwaga: nie możesz bezpośrednio edytować zawartości tej strony. Nie pojawia się ona na liście stron w portalu.

  

Co to jest zrzut specyfikacji OpenAPI?

Każda specyfikacja OpenAPI jest źródłem informacji w całym cyklu życia interfejsu API. Ta sama specyfikacja jest używana na każdym etapie cyklu życia interfejsu API, od programowania przez publikowanie po monitorowanie. Gdy modyfikujesz specyfikację, musisz pamiętać o wpływie zmian na interfejs API w innych fazach cyklu życia, zgodnie z opisem w sekcji Co się stanie, jeśli zmodyfikuję specyfikację?

Gdy publikujesz interfejs API, tworzysz zrzut specyfikacji OpenAPI, aby wygenerować dokumentację API. Ten zrzut reprezentuje konkretną wersję specyfikacji w sklepie ze specyfikacjami. Jeśli zmodyfikujesz specyfikację OpenAPI za pomocą edytora specyfikacji, możesz zrobić kolejny zrzut specyfikacji, aby odzwierciedlić najnowsze zmiany w dokumentacji API.

Dodawanie obsługi CORS do proxy interfejsów API

Przed opublikowaniem interfejsów API musisz dodać do serwerów proxy interfejsu API obsługę CORS, aby obsługiwać żądania współdzielenia po stronie klienta.

CORS (Cross-origin resource sharing) to standardowy mechanizm, który umożliwia wywoływanie w JavaScript XMLHttpRequest (XHR) wykonywanych na stronie internetowej wchodzenie w interakcje z zasobami z domen współdzielonych. CORS to powszechnie stosowane rozwiązanie zasady dotyczącej tej samej domeny, która jest egzekwowana przez wszystkie przeglądarki. Jeśli na przykład wywołasz interfejs API Twittera za pomocą XHR z kodu JavaScript działającego w przeglądarce, wywołanie zakończy się niepowodzeniem. Dzieje się tak, ponieważ domena, która wyświetla stronę w Twojej przeglądarce, nie jest taka sama jak domena, która wyświetla interfejs Twitter API. CORS rozwiązuje ten problem, umożliwiając serwerom „akceptację” współdzielenia zasobów między domenami.

Informacje o dodawaniu obsługi CORS do serwerów proxy interfejsu API przed opublikowaniem interfejsów API znajdziesz w artykule Dodawanie obsługi CORS do serwera proxy interfejsu API.

Uwaga: większość nowoczesnych przeglądarek wymusza CORS. Zapoznaj się z pełną listą obsługiwanych przeglądarek. Szczegółowy opis CORS znajdziesz w rekomendacji W3C dotyczącej współdzielenia zasobów pomiędzy serwerami z różnych domen.

Otwórz stronę interfejsów API

Aby otworzyć stronę interfejsów API:

1. Kliknij Opublikuj > Portale i wybierz portal.
2. Na stronie głównej portalu kliknij Interfejsy API.

Możesz też kliknąć Interfejsy API w menu portalu na górnym pasku nawigacyjnym.

Wyświetli się lista interfejsów API.

Jak widać na poprzednim rysunku, strona Interfejsy API umożliwia:

• Wyświetlanie szczegółów interfejsów API dostępnych w portalu
• Dodawanie interfejsu API do portalu
• Zrób migawkę specyfikacji OpenAPI powiązanej z produktem API, aby zaktualizować dokumentację API.
• Publikowanie i wycofywanie interfejsu API w portalu
• Zarządzanie odbiorcami interfejsu API w portalu
• Edytuj powiązaną specyfikację (patrz Tworzenie specyfikacji za pomocą edytora specyfikacji).
• Usuwanie interfejsu API z portalu
• Szybko identyfikuj „osierocone” interfejsy API, których powiązane usługi API zostały usunięte z Edge, i ponownie twórz usługi API lub usuwaj interfejsy API z portalu.

Dodawanie interfejsu API do portalu

Uwaga: do portalu możesz dodać maksymalnie 100 interfejsów API.

Aby dodać interfejs API do portalu:

1. Kliknij Opublikuj > Portale i wybierz portal.
2. Na stronie głównej portalu kliknij Interfejsy API.
   Możesz też wybrać Interfejsy API w menu portalu na górnym pasku nawigacyjnym.
3. Kliknij + API.
   Wyświetli się okno dialogowe Dodaj usługę API do portalu.

4. Na karcie Produkt API w oknie wybierz produkt API, który chcesz dodać do portalu.
   

5. Kliknij Dalej.

6. Wybierz źródło, które ma być użyte w zrzucie.
   Jeśli serwer proxy interfejsu API uwzględniony w produkcie API został utworzony przy użyciu specyfikacji OpenAPI, wybierz ją z menu.
   

   Możesz też wybrać:

   • Brak specyfikacji i dodać ją później po opublikowaniu interfejsu API, zgodnie z opisem w artykule Tworzenie migawki specyfikacji.
   • Wybierz inną specyfikację, aby wybrać lub przesłać nową specyfikację.

7. Zaznacz pole wyboru Opublikowano, aby opublikować interfejs API w portalu. Jeśli nie chcesz jeszcze publikować interfejsu API, odznacz opcję Opublikowano.
   Ustawienie możesz później zmienić zgodnie z opisem w artykule Publikowanie lub wycofywanie interfejsu API w portalu.

8. W sekcji Odbiorcy wybierz jedną z tych opcji, aby zarządzać odbiorcami interfejsu API, zezwalając na dostęp do:

   • Anonimowi użytkownicy, aby zezwolić wszystkim użytkownikom na wyświetlanie strony.
   • Zarejestrowani użytkownicy, aby zezwolić na wyświetlanie strony tylko zarejestrowanym użytkownikom.

   Ustawienie możesz później zmienić zgodnie z opisem w artykule Zarządzanie odbiorcami interfejsu API w portalu.

9. Kliknij Zakończ.

Zrób zrzut specyfikacji

Po opublikowaniu interfejsu API możesz w dowolnym momencie utworzyć nowy zrzut specyfikacji OpenAPI, aby zaktualizować dokumentację API opublikowaną w portalu.

Aby zrobić migawkę specyfikacji OpenAPI:

1. Kliknij Opublikuj > Portale i wybierz portal.
2. Na stronie głównej portalu kliknij Interfejsy API.
   Możesz też wybrać Interfejsy API w menu portalu na górnym pasku nawigacyjnym.
3. Umieść kursor nad interfejsem API, z którego chcesz zrobić zrzut, aby wyświetlić działania.

4. Kliknij .

   Uwaga: jeśli migawka jest aktualna w wybranym źródle specyfikacji, wyświetli się odpowiedni komunikat.

5. Wybierz istniejącą specyfikację z menu Snapshot Source (Źródło migawki) lub kliknij Choose a different spec (Wybierz inną specyfikację), aby wybrać lub przesłać nową specyfikację do generowania dokumentacji interfejsu API. Możesz też kliknąć Brak specyfikacji, aby usunąć bieżącą specyfikację.

6. Kliknij Zaktualizuj zrzut (lub Usuń zrzut, jeśli wybrano opcję Brak specyfikacji).

Dokumentacja API jest generowana na podstawie specyfikacji i dodawana do strony Dokumentacja API.

Publikowanie i cofanie publikacji interfejsu API w portalu

Aby opublikować interfejs API w portalu lub cofnąć jego publikację:

1. Kliknij Opublikuj > Portale i wybierz portal.
2. Na stronie głównej portalu kliknij Interfejsy API.
   Możesz też wybrać Interfejsy API w menu portalu na górnym pasku nawigacyjnym.
3. Umieść kursor na interfejsie API, który chcesz opublikować lub wycofać.
4. Kliknij .
5. Zaznacz pole wyboru Włączony, aby opublikować interfejs API w portalu. Odznacz opcję Włączony, aby wycofać publikację interfejsu API.
6. Kliknij Zapisz.

Zarządzanie odbiorcami interfejsu API w portalu

Zarządzaj odbiorcami interfejsu API w portalu, zezwalając na dostęp do:

• Wszyscy użytkownicy
• Tylko zarejestrowani użytkownicy

Aby zarządzać odbiorcami interfejsu API w portalu:

1. Kliknij Opublikuj > Portale i wybierz portal.
2. Na stronie głównej portalu kliknij Interfejsy API.
   Możesz też wybrać Interfejsy API w menu portalu na górnym pasku nawigacyjnym.
3. Umieść kursor nad interfejsem API, w przypadku którego chcesz zarządzać odbiorcami, aby wyświetlić działania.
4. Kliknij .
5. W sekcji Odbiorcy wybierz jedną z tych opcji:
   • Anonimowi użytkownicy, aby zezwolić wszystkim użytkownikom na wyświetlanie usługi API.
   • Zarejestrowani użytkownicy, aby zezwolić na wyświetlanie produktu interfejsu API tylko zarejestrowanym użytkownikom.
6. Kliknij Zapisz.

Usuwanie interfejsu API z portalu

Aby usunąć interfejs API z portalu:

1. Kliknij Opublikuj > Portale i wybierz portal.
2. Na stronie głównej portalu kliknij Interfejsy API.
   Możesz też wybrać Interfejsy API w menu portalu na górnym pasku nawigacyjnym.
3. Umieść kursor nad interfejsem API na liście, aby wyświetlić menu działań.
4. Kliknij .

Rozwiązywanie problemów z opublikowanymi interfejsami API

Jeśli podczas korzystania z opcji Wypróbuj pojawi się błąd TypeError: Failed to fetch, sprawdź te możliwe przyczyny i rozwiązania:

• W przypadku błędów dotyczących treści mieszanych przyczyną może być znany problem z swagger-ui. Jednym z możliwych rozwiązań jest upewnienie się, że w definicji schemes w specyfikacji OpenAPI przed HTTP podasz HTTPS. Na przykład:

   schemes:
     - https
     - http
  

• W przypadku błędów ograniczeń CORS (współdzielenia zasobów pomiędzy serwerami z różnych domen) sprawdź, czy Twoje proxy interfejsu API obsługują CORS. CORS to standardowy mechanizm, który umożliwia żądania współdzielenia po stronie klienta. Zobacz Dodawanie obsługi CORS do serwera proxy interfejsu API. Sprawdź też, czy w przeglądarce jest włączony mechanizm CORS.