Opublikuj swoje interfejsy API (wersja oryginalna)

Przeglądasz dokumentację Apigee Edge.
Otwórz dokumentację Apigee X. Informacje

Opublikuj interfejsy API w portalu, aby udostępnić je deweloperom aplikacji w sposób opisany w sekcjach poniżej.

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. Automatycznie generuj dokumentację referencyjną API na podstawie zrzutu specyfikacji OpenAPI, aby umożliwić deweloperom aplikacji zapoznanie się z Twoimi interfejsami API. Więcej informacji o migawkach znajdziesz w artykule Czym jest migawka specyfikacji OpenAPI?

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

• Do portalu zostanie dodana strona z informacjami o interfejsie API
  Na stronie „API Reference” (Materiały referencyjne interfejsu API) zobaczysz dokumentację API wygenerowaną automatycznie na podstawie zrzutu specyfikacji OpenAPI. Deweloperzy mogą zapoznać się z dokumentacją interfejsu API i kliknąć Wypróbuj, aby wysłać żądanie do interfejsu API i wyświetlić wyniki.

  Uwaga: nie możesz edytować zawartości tej strony bezpośrednio – nie jest ona widoczna na liście stron w Twoim portalu.

  

• Do strony interfejsów API został dodany link do strony z dokumentacją API
  Strona interfejsów API (dołączona do przykładowego portalu) zawiera listę wszystkich interfejsów API opublikowanych w Twoim portalu wraz z linkami do odpowiedniej dokumentacji referencyjnej dotyczącej interfejsów API, gdzie znajdziesz więcej informacji.

  Uwaga: nie możesz edytować zawartości tej strony bezpośrednio – nie jest ona widoczna na liście stron w Twoim portalu.

  

Czym jest migawka specyfikacji OpenAPI?

Każda specyfikacja OpenAPI służy za źródło informacji przez cały cykl życia interfejsu API. Ta sama specyfikacja jest używana na każdym etapie cyklu życia interfejsu API – od programowania, przez publikowanie, po monitorowanie. Modyfikując specyfikację, musisz rozumieć wpływ zmian na interfejs API na innych etapach cyklu życia, tak jak to opisano w sekcji Co się stanie, jeśli zmodyfikuję specyfikację?.

Gdy publikujesz interfejs API, tworzysz migawkę specyfikacji OpenAPI, aby wygenerować dokumentację dotyczącą API. Ten zrzut przedstawia konkretną wersję specyfikacji w magazynie specyfikacji. Jeśli zmodyfikujesz specyfikację OpenAPI za pomocą edytora specyfikacji, możesz zrobić zrzut ekranu specyfikacji, aby uwzględnić najnowsze zmiany w dokumentacji referencyjnej interfejsu API.

Dodaję obsługę CORS do serwerów proxy interfejsów API

Zanim opublikujesz interfejsy API, musisz dodać obsługę CORS do serwerów proxy interfejsów API, aby obsługiwać żądania po stronie klienta z innych domen.

CORS to standardowy mechanizm umożliwiający wywołanie JavaScriptu XMLHttpRequest (XHR) wykonywane na stronie internetowej na interakcję z zasobami z domen innych niż źródłowe. CORS to powszechnie stosowane rozwiązanie w przypadku zasady tego samego pochodzenia egzekwowane przez wszystkie przeglądarki. Jeśli na przykład wywołasz interfejs XHR API Twittera z kodu JavaScript uruchomionego w przeglądarce, nie uda się. Dzieje się tak, ponieważ domena udostępniająca stronę w przeglądarce różni się od domeny obsługującej interfejs Twitter API. CORS rozwiązuje ten problem, umożliwiając serwerom wyrażenie zgody na udostępnianie zasobów między domenami.

Informacje o dodawaniu obsługi CORS do serwerów proxy interfejsów 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 stosowanie CORS. Zapoznaj się z pełną listą obsługiwanych przeglądarek. Szczegółowy opis CORS znajdziesz w artykule na temat rekomendacji W3C dotyczących udostępniania zasobów między serwerami.

Poznawanie strony interfejsów API

Aby uzyskać dostęp do strony interfejsów API:

1. Kliknij Publish > Portals (Opublikuj > Portale) i wybierz swój portal.
2. Kliknij Interfejsy API na stronie głównej portalu.

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

Zostanie wyświetlona lista interfejsów API.

Jak już wspomnieliśmy na poprzednim ilustracji, strona interfejsów API umożliwia:

• Wyświetl szczegóły interfejsów API dostępnych w Twoim portalu
• Dodawanie interfejsu API do portalu
• Przejrzyj specyfikację OpenAPI powiązaną z danym produktem, aby zaktualizować dokumentację API.
• Publikowanie interfejsu API w portalu i cofanie jego publikacji
• Zarządzanie odbiorcami interfejsu API w portalu
• Zmień powiązaną specyfikację (zobacz Tworzenie specyfikacji w edytorze specyfikacji).
• Usuwanie interfejsu API z portalu
• Szybko zidentyfikuj „osierocone” interfejsy API, których powiązana usługa API została usunięta z Edge, i ponownie utwórz ją lub usuń 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 Publish > Portals (Opublikuj > Portale) i wybierz swój portal.
2. Kliknij Interfejsy API na stronie głównej portalu.
   Możesz też wybrać Interfejsy API w menu portalu na górnym pasku nawigacyjnym.
3. Kliknij + API.
   Pojawi się okno Dodaj usługę API do portalu.

4. W oknie na karcie Usługa API wybierz usługę, którą chcesz dodać do portalu.
   

5. Kliknij Dalej.

6. Wybierz źródło, którego chcesz używać ze zrzutem.
   Jeśli serwer proxy interfejsu API został utworzony w usłudze API zgodnie ze specyfikacją OpenAPI, wybierz specyfikację z listy.
   

   Możesz też wybrać jedną z tych opcji:

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

7. Zaznacz pole wyboru Publish (Opublikowano), aby opublikować interfejs API w portalu. Jeśli nie chcesz jeszcze publikować interfejsu API, odznacz Opublikowane.
   Możesz zmienić to ustawienie później zgodnie z opisem w artykule Publikowanie interfejsu API w portalu i cofanie jego publikacji.

8. W sekcji Odbiorcy wybierz jedną z poniższych opcji, aby zarządzać listą odbiorców interfejsu API, zezwalając na dostęp:

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

   Możesz zmienić to ustawienie później, zgodnie z opisem w sekcji Zarządzanie odbiorcami w interfejsie API w portalu.

9. Kliknij Zakończ.

Zrób zrzut ekranu specyfikacji

Po opublikowaniu interfejsu API możesz w każdej chwili zrobić nowe zrzut specyfikacji OpenAPI, aby zaktualizować opublikowaną w portalu dokumentację referencyjną.

Aby zrobić zrzut specyfikacji OpenAPI:

1. Kliknij Publish > Portals (Opublikuj > Portale) i wybierz swój portal.
2. Kliknij Interfejsy API na stronie głównej portalu.
   Możesz też wybrać Interfejsy API w menu portalu na górnym pasku nawigacyjnym.
3. Najedź kursorem na interfejs API, dla którego chcesz zrobić zrzut, aby wyświetlić działania.

4. Kliknij .

   Uwaga: jeśli zrzut jest aktualny z wybraną specyfikacją źródła, pojawi się komunikat.

5. Wybierz istniejącą specyfikację w menu Źródło zrzutu lub kliknij Wybierz inną specyfikację, aby wybrać lub przesłać nową specyfikację na potrzeby generowania dokumentacji interfejsu API. Możesz też wybrać Brak specyfikacji, aby usunąć bieżącą specyfikację.

6. Kliknij Aktualizuj zrzut ekranu (lub Usuń migawkę, jeśli wybierzesz opcję Brak specyfikacji).

Dokumentacja API jest generowana na podstawie specyfikacji i dodana do strony z dokumentacją interfejsu API.

Publikowanie i cofanie publikacji interfejsu API w portalu

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

1. Kliknij Publish > Portals (Opublikuj > Portale) i wybierz swój portal.
2. Kliknij Interfejsy API na stronie głównej portalu.
   Możesz też wybrać Interfejsy API w menu portalu na górnym pasku nawigacyjnym.
3. Najedź kursorem na interfejs API, który chcesz opublikować lub cofnąć.
4. Kliknij .
5. Zaznacz pole wyboru Włączone, aby opublikować interfejs API w portalu. Aby cofnąć publikację interfejsu API, odznacz Włączono.
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 Publish > Portals (Opublikuj > Portale) i wybierz swój portal.
2. Kliknij Interfejsy API na stronie głównej portalu.
   Możesz też wybrać Interfejsy API w menu portalu na górnym pasku nawigacyjnym.
3. Najedź kursorem na interfejs API, dla którego chcesz zarządzać listą odbiorców, aby wyświetlić działania.
4. Kliknij .
5. W sekcji Odbiorcy wybierz jedną z tych opcji:
   • Anonimowi użytkownicy, aby umożliwić wszystkim użytkownikom wyświetlanie usługi API.
   • Zarejestrowani użytkownicy, aby zezwolić na wyświetlanie usługi API tylko zarejestrowanych użytkownikom.
6. Kliknij Zapisz.

Usuwanie interfejsu API z portalu

Aby usunąć interfejs API z portalu:

1. Kliknij Publish > Portals (Opublikuj > Portale) i wybierz swój portal.
2. Kliknij Interfejsy API na stronie głównej portalu.
   Możesz też wybrać Interfejsy API w menu portalu na górnym pasku nawigacyjnym.
3. Najedź kursorem na interfejs API na liście, aby wyświetlić menu czynności.
4. Kliknij .

Rozwiązywanie problemów z opublikowanymi interfejsami API

Jeśli podczas korzystania z funkcji Wypróbuj to rozwiązanie, jeśli zostanie zwrócony błąd TypeError: Failed to fetch, weź pod uwagę te możliwe przyczyny i rozwiązania:

• W przypadku błędów związanych z treścią mieszaną błąd może być spowodowany przez znany problem z elementami interfejsu. Jednym z rozwiązań tymczasowych jest zapewnienie, że HTTPS przed HTTP jest określony w definicji schemes w specyfikacji OpenAPI. Na przykład:

   schemes:
     - https
     - http
  

• W przypadku błędów ograniczeń CORS (udostępnianie zasobów między domenami) upewnij się, że CORS jest obsługiwane przez serwery proxy interfejsu API. CORS to standardowy mechanizm, który umożliwia obsługę żądań z innych domen po stronie klienta. Zobacz Dodawanie obsługi CORS dla serwera proxy interfejsu API. Upewnij się też, że w przeglądarce jest włączony CORS.