Wyświetlasz dokumentację Apigee Edge.
Otwórz dokumentację Apigee X. info
Opublikuj interfejsy API w portalu, aby udostępnić je deweloperom aplikacji, jak opisano w sekcjach poniżej.
Omówienie publikowania interfejsów API
Proces publikowania interfejsów API w portalu składa się z 2 etapów:
- Wybierz usługę API, którą chcesz opublikować w portalu.
- Wyświetlaj dokumentację API z dokumentu OpenAPI lub schematu GraphQL, aby deweloperzy aplikacji mogli dowiedzieć się więcej o Twoich interfejsach API. (Więcej informacji o zrzutach znajdziesz w artykule Co to jest zrzut?).
Co jest publikowane w portalu?
Gdy opublikujesz interfejs API, w portalu automatycznie zostaną wprowadzone te zmiany:
- Dokumentacja API Dostępny interfejs zależy od tego, czy publikujesz interfejs API za pomocą dokumentu OpenAPI czy schematu GraphQL. Zobacz:
- Na stronie interfejsów API dodano link do strony dokumentacji interfejsu API
Strona interfejsów API (dołączona do przykładowego portalu) zawiera listę wszystkich interfejsów API opublikowanych w Twoim portalu, ułożonych w porządku alfabetycznym, z linkami do dokumentacji referencyjnej poszczególnych interfejsów API, w której znajdziesz więcej informacji. Opcjonalnie możesz dostosować:
- Obraz wyświetlany na każdej karcie interfejsu API
- Kategorie używane do tagowania interfejsów API, aby umożliwić programistom odkrywanie powiązanych interfejsów API na stronie interfejsów API.

SmartDocs (OpenAPI)
Gdy opublikujesz interfejs API za pomocą dokumentu OpenAPI, do portalu zostanie dodana dokumentacja referencyjna interfejsu SmartDocs API.
Deweloperzy mogą zapoznać się z dokumentacją referencyjną interfejsu API SmartDocs i użyć panelu Wypróbuj ten interfejs API, aby wysłać żądanie do interfejsu API i wyświetlić dane wyjściowe. Wypróbuj ten interfejs API działa z niezabezpieczonymi lub zabezpieczonymi punktami końcowymi, które korzystają z uwierzytelniania podstawowego, za pomocą klucza interfejsu API lub OAuth, w zależności od metody zabezpieczeń zdefiniowanej w dokumencie OpenAPI. W przypadku OAuth obsługiwane są te przepływy: kod autoryzacji, hasło i dane logowania klienta.
Kliknij
Pełny ekran, aby rozwinąć panel Wypróbuj ten interfejs API. Rozwinięty panel umożliwia wyświetlanie wywołania curl i przykładowych fragmentów kodu w różnych formatach, takich jak HTTP, Python, Node.js i inne, jak pokazano na poniższym rysunku.

Eksplorator GraphQL
Gdy opublikujesz interfejs API za pomocą schematu GraphQL, do portalu zostanie dodany Eksplorator GraphQL. GraphQL Explorer to interaktywne środowisko do uruchamiania zapytań w interfejsie API. Eksplorer jest oparty na GraphiQL, czyli referencyjnej implementacji środowiska IDE GraphQL opracowanej przez GraphQL Foundation.
Programiści mogą używać eksploratora GraphQL do przeglądania interaktywnej dokumentacji opartej na schemacie, tworzenia i uruchamiania zapytań, wyświetlania wyników zapytań oraz pobierania schematu. Aby zabezpieczyć dostęp do interfejsu API, deweloperzy mogą przekazywać nagłówki autoryzacji w panelu Nagłówki żądania.
Więcej informacji o GraphQL znajdziesz na stronie graphql.org.

Co to jest migawka?
Każdy dokument OpenAPI lub GraphQL jest źródłem informacji w całym cyklu życia interfejsu API. Ten sam dokument jest używany na każdym etapie cyklu życia interfejsu API, od tworzenia po publikowanie i monitorowanie. Gdy modyfikujesz dokument, 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ę dokument?.
Gdy opublikujesz interfejs API, utworzysz zrzut dokumentu OpenAPI lub GraphQL, aby wyrenderować dokumentację API. Ten zrzut reprezentuje konkretną wersję dokumentu. Jeśli zmodyfikujesz dokument, możesz zrobić kolejny zrzut, aby odzwierciedlić najnowsze zmiany w dokumentacji API.
Informacje o adresach URL wywołania zwrotnego
Jeśli Twoje aplikacje wymagają adresu URL wywołania zwrotnego, np. w przypadku korzystania z typu przyznawania kodu autoryzacji OAuth 2.0 (często określanego jako trzyskładnikowe uwierzytelnianie OAuth), możesz wymagać od deweloperów podania adresu URL wywołania zwrotnego podczas rejestrowania aplikacji. Adres URL wywołania zwrotnego zwykle określa adres URL aplikacji, która jest przeznaczona do otrzymywania kodu autoryzacji w imieniu aplikacji klienta. Więcej informacji znajdziesz w artykule Implementowanie typu przyznawania uprawnień za pomocą kodu autoryzacji.
Podczas dodawania interfejsu API do portalu możesz skonfigurować, czy podczas rejestracji aplikacji wymagany jest URL wywołania zwrotnego. To ustawienie możesz zmienić w każdej chwili, postępując zgodnie z instrukcjami w artykule Zarządzanie adresem URL wywołania zwrotnego interfejsu API.
Podczas rejestrowania aplikacji deweloperzy muszą podać adres URL wywołania zwrotnego dla wszystkich interfejsów API, które tego wymagają, zgodnie z opisem w sekcji Rejestrowanie aplikacji.
Konfigurowanie proxy interfejsu API pod kątem obsługi funkcji „Wypróbuj ten interfejs API”
Zanim opublikujesz interfejsy API za pomocą dokumentu OpenAPI, musisz skonfigurować proxy interfejsu API, aby obsługiwał wysyłanie żądań w panelu Wypróbuj ten interfejs API w dokumentacji referencyjnej interfejsu SmartDocs API. Aby to zrobić:
Dodawanie obsługi CORS do proxy interfejsów API w celu wymuszania żądań z różnych domen po stronie klienta
CORS to standardowy mechanizm, który umożliwia wywoływanie w JavaScript XMLHttpRequest (XHR) wykonywanych na stronie internetowej w celu interakcji z zasobami z domen innych niż domena źródłowa. CORS to powszechnie stosowane rozwiązanie zasady dotyczącej tej samej domeny, która jest egzekwowana przez wszystkie przeglądarki.
Zaktualizuj konfigurację proxy interfejsu API, jeśli używasz uwierzytelniania podstawowego lub OAuth2.
W tabeli poniżej znajdziesz podsumowanie wymagań dotyczących konfiguracji proxy interfejsu API, które umożliwiają obsługę panelu Wypróbuj ten interfejs API w dokumentacji referencyjnej interfejsu SmartDocs API na podstawie dostępu do uwierzytelniania.
| Dostęp do uwierzytelniania | Wymagania dotyczące konfiguracji zasad |
|---|---|
| Brak lub klucz interfejsu API | Dodaj obsługę CORS do proxy interfejsu API. Aby ułatwić sobie pracę, skorzystaj z przykładowego rozwiązania CORS udostępnionego w GitHubie lub wykonaj czynności opisane w sekcji Dodawanie obsługi CORS do proxy interfejsu API. |
| Podstawowe uwierzytelnianie | Wykonaj te czynności:
|
| OAuth2 |
|
Zarządzaj interfejsami API
Zarządzaj interfejsami API w sposób opisany w sekcjach poniżej.
Przeglądaj interfejsy API
Aby wyświetlić interfejsy API w portalu, użyj interfejsu lub polecenia curl.
UI
Aby wyświetlić katalog interfejsów API:
- Kliknij Opublikuj > Portale i wybierz portal.
- Na stronie głównej portalu kliknij Katalog interfejsów API. Możesz też wybrać Katalog interfejsów API w menu portalu na pasku nawigacyjnym u góry.
Na karcie Interfejsy API w katalogu interfejsów API wyświetla się lista interfejsów API, które zostały dodane do portalu.

Jak widać na poprzednim rysunku, karta Interfejsy API umożliwia:
- Wyświetlanie szczegółów interfejsów API dostępnych w portalu
- Dodawanie interfejsu API do portalu
- Aby edytować interfejs API w portalu, wykonaj co najmniej jedno z tych zadań:
- Zarządzanie migawką dokumentu powiązanego z produktem API w celu aktualizowania dokumentacji API.
- Publikowanie i wycofywanie interfejsu API w portalu
- Zarządzanie widocznością interfejsu API w portalu:
- Zarządzanie adresem URL wywołania zwrotnego interfejsu API
- Zarządzanie obrazem na karcie interfejsu API
- Tagowanie interfejsu API za pomocą kategorii
- Edytowanie nazwy i opisu interfejsu API
- Usuwanie interfejsu API z portalu
- Zarządzanie kategoriami używanymi do wykrywania powiązanych interfejsów API
- Szybkie wykrywanie specyfikacji, które są nieaktualne lub zostały usunięte ze sklepu ze specyfikacjami.
- Szybko identyfikuj osierocone interfejsy API, których powiązana usługa API została usunięta z Apigee Edge, i ponownie twórz usługę API lub usuwaj interfejs API z portalu.
curl
Aby wyświetlić listę interfejsów API:
curl -X GET "https://api.enterprise.apigee.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs" \
-H "Authorization: Bearer ACCESS_TOKEN"
Zastąp następujące elementy:
-
ORG_NAME nazwą organizacji. Na przykład:
my-org. -
SITE_ID z nazwą portalu w formacie ORG_NAME-PORTAL_NAME, gdzie ORG_NAME to nazwa organizacji, a PORTAL_NAME to nazwa portalu przekonwertowana na małe litery z usuniętymi spacjami i myślnikami. Na przykład:
my-org-myportal. - ACCESS_TOKEN z tokenem uwierzytelniania używanym do uzyskiwania dostępu do interfejsu Apigee Edge API. Więcej informacji o uwierzytelnianiu i tokenach znajdziesz w artykule Uwierzytelnianie dostępu do interfejsu Edge API.
Instrukcje dotyczące używania podziału na strony w treści odpowiedzi znajdziesz w uwagach na temat podziału na strony.
Ładunek odpowiedzi:
{
"status": "success",
"message": "one page of apidocs returned",
"data": [
{
"id": 622759,
"siteId": "my-org-myportal",
"title": "Test",
"description": "",
"published": false,
"visibility": false,
"apiId": "apiproducttest18",
"apiProductName": "apiproduct_test18",
"edgeAPIProductName": "apiproduct_test18",
"specId": null,
"specContent": null,
"specTitle": null,
"snapshotExists": false,
"snapshotModified": null,
"modified": 1724144471000,
"anonAllowed": false,
"imageUrl": null,
"snapshotState": null,
"requireCallbackUrl": false,
"categoryIds": [],
"specFormat": null,
"specModified": null,
"snapshotOutdated": false,
"snapshotSourceMissing": false,
"graphqlSchema": null,
"graphqlEndpointUrl": null,
"graphqlSchemaDisplayName": null,
"grpcFileName": null,
"grpcZipContent": null
}
],
"code": null,
"request_id": "1452867334",
"error_code": null,
"next_page_token": ""
}
Gdzie:
-
modified: czas ostatniej modyfikacji elementu katalogu w milisekundach od początku epoki. Na przykład:1698165480000. -
id: identyfikator produktu w katalogu. Na przykład:399668.
Uwagi dotyczące paginacji:
Rozmiar strony: użyj parametru
pageSize, aby określić liczbę elementów listy, które mają być zwracane na jednej stronie. Wartość domyślna to 25, a maksymalna – 100. Jeśli są dodatkowe strony, polenextPageTokenjest wypełniane tokenem:curl -X GET "https://api.enterprise.apigee.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs?pageSize=PAGE_SIZE" \ -H "Authorization: Bearer ACCESS_TOKEN"
Zastąp:
- PAGE_SIZE z liczbą elementów listy, które mają być zwracane na jednej stronie. Na przykład 10.
Ładunek odpowiedzi:
{ "status": "success", "message": "one page of apidocs returned", "data": [ { "id": 638007, "siteId": "tsnow-mint-liztest", "title": "Testing", "description": "", "published": false, "visibility": false, "apiId": "testcatalog", "apiProductName": "testcatalog", "edgeAPIProductName": "testcatalog", "specId": "Petstore", "specContent": null, "specTitle": null, "snapshotExists": true, "snapshotModified": 1726508367000, "modified": 1728582504000, "anonAllowed": false, "imageUrl": null, "snapshotState": "OK_SUBMITTED", "requireCallbackUrl": false, "categoryIds": [], "specFormat": "YAML", "specModified": null, "snapshotOutdated": false, "snapshotSourceMissing": false, "graphqlSchema": null, "graphqlEndpointUrl": null, "graphqlSchemaDisplayName": null, "grpcFileName": null, "grpcZipContent": null } ], "code": null, "request_id": "1068810934", "error_code": null, "next_page_token": "" }Token strony: użyj
pageToken, aby pobrać kolejne strony, jeśli jest ich więcej niż jedna:curl -X GET "https://api.enterprise.apigee.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs?pageSize=PAGE_SIZE&pageToken=PAGE_TOKEN" \ -H "Authorization: Bearer ACCESS_TOKEN"Zastąp:
- PAGE_SIZE z liczbą elementów listy, które mają być zwracane na jednej stronie. Na przykład 10.
-
PAGE_TOKEN z wartością
nextPageToken. Na przykład:7zcqrin9l6xhi4nbrb9.
Dodaj interfejs API
Aby dodać interfejsy API do portalu, użyj interfejsu lub polecenia curl:
UI
Aby dodać interfejs API do portalu:
- Uzyskaj dostęp do katalogu interfejsów API.
- Kliknij kartę Interfejsy API, jeśli nie jest jeszcze wybrana.
Kliknij + Dodaj.
Wyświetli się okno Dodaj produkt interfejsu API do katalogu.
Wybierz usługę API, którą chcesz dodać do portalu.
Kliknij Dalej. Wyświetli się strona Szczegóły interfejsu API.
Skonfiguruj zawartość dokumentacji API i jej widoczność w portalu:
Pole Opis Opublikowano Aby opublikować interfejs API w portalu, kliknij Opublikowano. Jeśli nie chcesz jeszcze opublikować interfejsu API, wyczyść pole wyboru. Możesz później zmienić to ustawienie, jak opisano w artykule Publikowanie i wycofywanie interfejsu API w portalu. Wyświetl tytuł Zaktualizuj tytuł interfejsu API wyświetlany w katalogu. Domyślnie używana jest nazwa usługi API. Wyświetlaną nazwę możesz później zmienić, jak opisano w sekcji Edytowanie wyświetlanej nazwy i opisu. Wyświetl opis Zaktualizuj opis interfejsu API wyświetlany w katalogu. Domyślnie używany jest opis usługi API. Wyświetlany opis możesz później zmienić zgodnie z instrukcjami w artykule Edytowanie wyświetlanego tytułu i opisu. Wymagaj od programistów określania adresu URL wywołania zwrotnego Włącz tę opcję, jeśli chcesz wymagać od programistów aplikacji określania adresu URL wywołania zwrotnego. Adres URL wywołania zwrotnego możesz dodać lub zaktualizować później, zgodnie z opisem w sekcji Zarządzanie adresem URL wywołania zwrotnego interfejsu API. Dokumentacja API Aby użyć dokumentu OpenAPI:
- Kliknij Dokument OpenAPI.
- Kliknij Wybierz dokument.
- Wykonaj jedną z tych czynności:
- Kliknij kartę Moje specyfikacje i wybierz specyfikację z Centrum specyfikacji.
- Kliknij kartę Prześlij plik i prześlij plik.
- Kliknij kartę Importuj z adresu URL i zaimportuj specyfikację z adresu URL.
- Kliknij Wybierz.
Aby użyć schematu GraphQL:
- Wybierz Schemat GraphQL.
- Kliknij Wybierz dokument.
- Znajdź i wybierz schemat GraphQL.
- Kliknij Wybierz.
Możesz też kliknąć No documentation (Brak dokumentacji) i dodać dokument później, po dodaniu interfejsu API, zgodnie z opisem w artykule Zarządzanie migawką dokumentu.
Widoczność interfejsu API Jeśli nie korzystasz z wersji beta funkcji zarządzania odbiorcami, wybierz jedną z tych opcji:
- Anonimowi użytkownicy, aby umożliwić wszystkim użytkownikom wyświetlanie interfejsu API.
- Zarejestrowani użytkownicy, aby zezwolić na wyświetlanie interfejsu API tylko zarejestrowanym użytkownikom.
Jeśli korzystasz z wersji beta funkcji zarządzania odbiorcami, wybierz jedną z tych opcji:
- Publiczny (widoczny dla każdego), aby umożliwić wszystkim użytkownikom wyświetlanie interfejsu API.
- Uwierzytelnieni użytkownicy, aby zezwolić na wyświetlanie interfejsu API tylko zarejestrowanym użytkownikom.
- Wybrani odbiorcy, aby wybrać konkretnych odbiorców, którzy będą mogli wyświetlać interfejs API.
Widocznością odbiorców możesz zarządzać później, zgodnie z opisem w artykule Zarządzanie widocznością interfejsu API w portalu.
Wyświetlany obrazy Aby wyświetlić obraz na karcie interfejsu API na stronie Interfejsy API, kliknij Wybierz obraz. W oknie Wybierz obraz wybierz istniejący obraz, prześlij nowy lub podaj adres URL zewnętrznego obrazu i kliknij Wybierz. Wyświetl podgląd miniatury interfejsu API i kliknij Wybierz. Obraz możesz dodać później, zgodnie z instrukcjami w artykule Zarządzanie obrazem na karcie interfejsu API. Jeśli określisz obraz za pomocą zewnętrznego adresu URL, nie zostanie on przesłany do Twoich zasobów. Ponadto wczytywanie obrazu w zintegrowanym portalu będzie zależeć od jego dostępności, która może być blokowana lub ograniczana przez zasady bezpieczeństwa treści. Kategorie Dodaj kategorie, do których będzie przypisany interfejs API, aby umożliwić deweloperom aplikacji odkrywanie powiązanych interfejsów API na stronie interfejsów API. Aby zidentyfikować kategorię:
- Wybierz kategorię z listy.
- Dodaj nową kategorię, wpisując jej nazwę i naciskając Enter. Nowa kategoria zostanie dodana do strony Kategorie i będzie dostępna podczas dodawania lub edytowania innych interfejsów API.
Kliknij Zapisz.
curl
Aby dodać interfejs API do portalu :
curl -X POST "https://api.enterprise.apigee.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs" \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"title": "TITLE",
"description": "DESCRIPTION",
"anonAllowed": ANON_TRUE_OR_FALSE,
"imageUrl": "IMAGE_URL",
"requireCallbackUrl": CALLBACK_TRUE_OR_FALSE,
"categoryIds": [
"CATEGORY_ID1",
"CATEGORY_ID2"
],
"published": PUBLISHED_TRUE_OR_FALSE,
"apiProductName": "API_PRODUCT"
}'
Zastąp następujące elementy:
-
ORG_NAME nazwą organizacji. Na przykład:
my-org. -
SITE_ID z nazwą portalu w formacie ORG_NAME-PORTAL_NAME, gdzie ORG_NAME to nazwa organizacji, a PORTAL_NAME to nazwa portalu przekonwertowana na małe litery z usuniętymi spacjami i myślnikami. Na przykład:
my-org-myportal. - ACCESS_TOKEN z tokenem uwierzytelniania używanym do uzyskiwania dostępu do interfejsu Apigee Edge API. Więcej informacji o uwierzytelnianiu i tokenach znajdziesz w artykule Uwierzytelnianie dostępu do interfejsu Edge API.
-
TITLE z wyświetlanym tytułem. Na przykład:
Hello World 2. -
DESCRIPTION z opisem wyświetlacza. Na przykład:
Simple hello world example. -
ANON_TRUE_OR_FALSE z
truelubfalse(domyślnie), gdzie:trueoznacza, że ten interfejs API jest publicznie widoczny i można go wyświetlać anonimowo; w przeciwnym razie mogą go wyświetlać tylko zarejestrowani użytkownicy. -
IMAGE_URL adresem URL zewnętrznego obrazu używanego w przypadku produktu w katalogu lub ścieżką do plików obrazów przechowywanych w portalu, np.
/files/book-tree.jpg. Jeśli podasz adres URL zewnętrznego obrazu, nie zostanie on przesłany do Twoich komponentów. Ponadto wczytywanie obrazu w zintegrowanym portalu będzie zależeć od jego dostępności, która może być blokowana lub ograniczana przez zasady bezpieczeństwa treści. -
CALLBACK_TRUE_OR_FALSE z
truelubfalse(domyślnie), gdzie:truewymaga od użytkownika portalu wpisania adresu URL podczas zarządzania aplikacją. -
CATEGORY_ID z identyfikatorem kategorii. Na przykład:
bf6505eb-2a0f-47af-a00a-ded40ac72960. Kolejne identyfikatory kategorii oddziel przecinkami. Pobierz identyfikator kategorii za pomocą polecenia list API categories. -
PUBLISHED_TRUE_OR_FALSE z wartością
truelubfalse(domyślnie), gdzietrueoznacza, że interfejs API jest dostępny publicznie. Po opublikowaniu możesz zezwolić na dostęp wszystkim użytkownikom, uwierzytelnionym użytkownikom lub konkretnym użytkownikom. -
API_PRODUCT z nazwą usługi API. Na przykład:
Hello World 2.
Ładunek odpowiedzi:
{
"status": "success",
"message": "API created",
"data": {
"id": 662423,
"siteId": "my-org-myportal",
"title": "My Test Catalog 4",
"description": "",
"published": false,
"visibility": false,
"apiId": "uxb9wjua",
"apiProductName": "uXB9wJUa",
"edgeAPIProductName": "uXB9wJUa",
"specId": null,
"specContent": null,
"specTitle": null,
"snapshotExists": false,
"snapshotModified": null,
"modified": 1729635493000,
"anonAllowed": false,
"imageUrl": null,
"snapshotState": null,
"requireCallbackUrl": false,
"categoryIds": [],
"specFormat": null,
"specModified": null,
"snapshotOutdated": null,
"snapshotSourceMissing": false,
"graphqlSchema": null,
"graphqlEndpointUrl": null,
"graphqlSchemaDisplayName": null,
"grpcFileName": null,
"grpcZipContent": null
},
"code": null,
"request_id": "893346193",
"error_code": null
}
Gdzie:
-
modified: czas ostatniej modyfikacji elementu katalogu w milisekundach od początku epoki. Na przykład:1698165480000. -
id: identyfikator produktu w katalogu. Na przykład:399668.
Edytowanie interfejsu API
Po dodaniu interfejsu API możesz wprowadzać zmiany za pomocą interfejsu lub wywołania interfejsu API.
W tej sekcji znajdziesz szczegółowy przykład czynności, które należy wykonać, aby zmodyfikować istniejący interfejs API w portalu.
Szczegółowe ustawienia modyfikacji znajdziesz w kolejnych sekcjach.
UI
Aby edytować interfejs API:
- Uzyskaj dostęp do katalogu interfejsów API.
- Kliknij kartę Interfejsy API, jeśli nie jest jeszcze wybrana.
- Kliknij wiersz interfejsu API, który chcesz edytować.
- Kliknij
Edytuj. - Wprowadź zmiany w sekcji Szczegóły interfejsu API. Opisy opcji znajdziesz w sekcji Dodawanie interfejsu API.
- Kliknij Zapisz.
curl
Po dodaniu interfejsu API użyj wywołania update, aby wprowadzić zmiany.
W tym przykładzie pokazujemy, jak zmienić stan opublikowania interfejsu API w portalu z true na false. W razie potrzeby możesz zmienić więcej niż jedno ustawienie w jednym wywołaniu interfejsu API.
- Aby znaleźć wygenerowany
id, który jednoznacznie identyfikuje każdy interfejs API, pobierz listę interfejsów API w portalu zgodnie z opisem w sekcji Eksplorowanie interfejsów API. Zwracanie bieżących wartości dla konkretnego interfejsu API:
curl -X GET "https://api.enterprise.apigee.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC" \ -H "Authorization: Bearer ACCESS_TOKEN"
Zastąp następujące elementy:
-
ORG_NAME nazwą organizacji. Na przykład:
my-org. -
SITE_ID z nazwą portalu w formacie ORG_NAME-PORTAL_NAME, gdzie ORG_NAME to nazwa organizacji, a PORTAL_NAME to nazwa portalu przekonwertowana na małe litery z usuniętymi spacjami i myślnikami. Na przykład:
my-org-myportal. -
API_DOC z wygenerowanym
iddokumentu. Na przykład:399668. Aby znaleźć tę wartość, użyj polecenia list API docs (lista dokumentów interfejsu API). - ACCESS_TOKEN z tokenem uwierzytelniania używanym do uzyskiwania dostępu do interfejsu Apigee Edge API. Więcej informacji o uwierzytelnianiu i tokenach znajdziesz w artykule Uwierzytelnianie dostępu do interfejsu Edge API.
Ładunek odpowiedzi:
{ "status": "success", "message": "apidoc returned", "data": { "id": 662423, "siteId": "my-org-myportal", "title": "My Test Catalog 4", "description": "", "published": false, "visibility": false, "apiId": "uxb9wjua", "apiProductName": "uXB9wJUa", "edgeAPIProductName": "uXB9wJUa", "specId": null, "specContent": null, "specTitle": null, "snapshotExists": false, "snapshotModified": null, "modified": 1729635493000, "anonAllowed": false, "imageUrl": null, "snapshotState": null, "requireCallbackUrl": false, "categoryIds": [], "specFormat": null, "specModified": null, "snapshotOutdated": false, "snapshotSourceMissing": false, "graphqlSchema": null, "graphqlEndpointUrl": null, "graphqlSchemaDisplayName": null, "grpcFileName": null, "grpcZipContent": null }, "code": null, "request_id": "601210268", "error_code": null }-
ORG_NAME nazwą organizacji. Na przykład:
W wywołaniu update uwzględnij wartości, które chcesz zachować, i zmodyfikuj te, które chcesz zmienić. Jeśli pominiesz wiersz, użyte zostanie ustawienie domyślne. W tym przykładzie zmień ustawienie publikacji z
falsenatrue:curl -X PUT "https://api.enterprise.apigee.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC" \ -H "Authorization: Bearer ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "title": "TITLE", "anonAllowed": true, "published": true }'Zastąp następujące elementy:
-
TITLE z wyświetlanym tytułem. Na przykład:
Hello World 2.
Ładunek odpowiedzi:
{ "status": "success", "message": "ApiDoc updated", "data": { "id": 662423, "siteId": "my-org-myportal", "title": "My Test Catalog 4", "description": "", "published": true, "visibility": true, "apiId": "uxb9wjua", "apiProductName": "uXB9wJUa", "edgeAPIProductName": "uXB9wJUa", "specId": null, "specContent": null, "specTitle": null, "snapshotExists": false, "snapshotModified": null, "modified": 1729989250000, "anonAllowed": true, "imageUrl": null, "snapshotState": null, "requireCallbackUrl": false, "categoryIds": [], "specFormat": null, "specModified": null, "snapshotOutdated": null, "snapshotSourceMissing": false, "graphqlSchema": null, "graphqlEndpointUrl": null, "graphqlSchemaDisplayName": null, "grpcFileName": null, "grpcZipContent": null }, "code": null, "request_id": "738172002", "error_code": null }-
TITLE z wyświetlanym tytułem. Na przykład:
Zarządzanie zrzutem dokumentu
Po opublikowaniu interfejsu API możesz w dowolnym momencie utworzyć nowy zrzut dokumentu OpenAPI lub GraphQL, aby zaktualizować dokumentację API opublikowaną w portalu.
Aby zarządzać zrzutem dokumentu:
- Uzyskaj dostęp do katalogu interfejsów API.
- Kliknij kartę Interfejsy API, jeśli nie jest jeszcze wybrana.
- Kliknij wiersz interfejsu API, który chcesz edytować.
- Sprawdź stan zrzutu.
Jeśli jest nieaktualny, wyświetli się ten komunikat:

- Kliknij
. - Wykonaj jedną z tych czynności:
- Aby odświeżyć nieaktualny zrzut dokumentu OpenAPI, kliknij Odśwież zrzut.
- Aby zmienić dokument używany do generowania dokumentacji interfejsu API, w sekcji Dokumentacja interfejsu API kliknij Wybierz dokument i wybierz nowy dokument.
- Kliknij Zapisz.
Publikowanie i cofanie publikacji interfejsu API w portalu
Publikowanie to proces udostępniania interfejsów API programistom aplikacji do wykorzystania.
Użyj interfejsu lub polecenia curl, aby opublikować lub cofnąć publikację interfejsu API w portalu.
UI
Aby opublikować interfejs API w portalu lub cofnąć jego publikację:
- Uzyskaj dostęp do katalogu interfejsów API.
- Kliknij kartę Interfejsy API, jeśli nie jest jeszcze wybrana.
- Kliknij wiersz interfejsu API, który chcesz edytować.
- Kliknij
Edytuj. - W sekcji Szczegóły interfejsu API zaznacz lub odznacz opcję Opublikowany (w katalogu), aby odpowiednio opublikować lub wycofać publikację interfejsu API w portalu.
- Kliknij Zapisz.
curl
W wywołaniu aktualizacji umieść jeden z tych elementów:
"published": true, # API is published to your portal "published": false, # API is not published in your portal
Aby edytować interfejs API:
-
curl -X GET "https://api.enterprise.apigee.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs" \ -H "Authorization: Bearer ACCESS_TOKEN"
Aby edytować interfejs API, użyj wywołania update. Uwzględnij zmienne wartości, które chcesz zachować, i zmodyfikuj wartości, które chcesz zmienić. Jeśli pominiesz ustawienie, które można zmieniać, zostanie ono zastąpione wartością domyślną.
curl -X PUT "https://api.enterprise.apigee.com/v1/organizations/ ORG_NAME/sites/SITE_ID/apidocs/API_DOC" \ -H "Authorization: Bearer ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "title": "TITLE", "description": "DESCRIPTION", "anonAllowed": ANON_TRUE_OR_FALSE, "imageUrl": IMAGE_URL, "requireCallbackUrl": CALLBACK_TRUE_OR_FALSE, "categoryIds": [ "CATEGORY_ID1", "CATEGORY_ID2" ], "published": PUBLISHED_TRUE_OR_FALSE }
Szczegółowy przykład kroków, zmiennych i zwróconego ładunku znajdziesz w artykule Zarządzanie wersją dokumentu.
Zarządzanie widocznością interfejsu API w portalu
Zarządzaj widocznością interfejsu API w portalu, zezwalając na dostęp do:
- Publiczne (widoczne dla każdego)
- Uwierzytelnieni użytkownicy:
- Wybrani odbiorcy (jeśli uczestniczysz w programie beta funkcji zarządzania odbiorcami)
Aby zarządzać widocznością interfejsu API w portalu, użyj interfejsu lub polecenia curl:
UI
Aby zarządzać widocznością interfejsu API w portalu:
- Uzyskaj dostęp do katalogu interfejsów API.
- Kliknij kartę Interfejsy API, jeśli nie jest jeszcze wybrana.
- Kliknij wiersz interfejsu API, który chcesz edytować.
- Kliknij
Edytuj. Wybierz ustawienie widoczności. Jeśli uczestniczysz w programie testów beta funkcji odbiorców, wybierz jedną z tych opcji:
- Publiczny (widoczny dla wszystkich), aby umożliwić wszystkim użytkownikom wyświetlanie strony.
- Uwierzytelnieni użytkownicy, aby zezwolić na wyświetlanie strony tylko zarejestrowanym użytkownikom.
- Wybrani odbiorcy, aby wybrać konkretnych odbiorców, którzy mają mieć możliwość wyświetlania strony. Zobacz Zarządzanie odbiorcami w portalu.
- Anonimowi użytkownicy, aby umożliwić wszystkim użytkownikom wyświetlanie strony.
- Zarejestrowani użytkownicy, aby zezwolić na wyświetlanie strony tylko zarejestrowanym użytkownikom.
Kliknij Prześlij.
curl
Jeśli masz dostęp do wersji beta funkcji zarządzania odbiorcami, używaj interfejsu do zarządzania odbiorcami.
Jeśli nie korzystasz z funkcji zarządzania odbiorcami, widoczność jest kontrolowana za pomocą anonAllowed.
W wywołaniu update
umieść jeden z tych elementów:
# When not enrolled in the beta release of the audience management feature: "anonAllowed": true, # Anonymous users can see the API "anonAllowed": false, # Only registered users can see the API
Aby edytować interfejs API:
-
curl -X GET "https://api.enterprise.apigee.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC" \ -H "Authorization: Bearer ACCESS_TOKEN" Aby edytować interfejs API, użyj wywołania update. Uwzględnij zmienne wartości, które chcesz zachować, i zmień wartości, które chcesz zmienić. Jeśli pominiesz ustawienie podlegające zmianom, używana jest wartość domyślna.
curl -X PUT "https://api.enterprise.apigee.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC" \ -H "Authorization: Bearer ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "title": "TITLE", "description": "DESCRIPTION", "anonAllowed": ANON_TRUE_OR_FALSE, "imageUrl": IMAGE_URL, "requireCallbackUrl": CALLBACK_TRUE_OR_FALSE, "categoryIds": [ "CATEGORY_ID1", "CATEGORY_ID2" ], "published": PUBLISHED_TRUE_OR_FALSE }'
Szczegółowy przykład czynności, zmiennych i zwracanego ładunku znajdziesz w artykule Edytowanie interfejsu API.
Zarządzanie adresem URL wywołania zwrotnego interfejsu API
Zarządzaj adresem URL wywołania zwrotnego interfejsu API. Zobacz artykuł o adresach URL wywołania zwrotnego.
Aby zarządzać adresem URL wywołania zwrotnego interfejsu API, użyj interfejsu lub polecenia curl:
UI
Aby zarządzać adresem URL wywołania zwrotnego interfejsu API:
- Uzyskaj dostęp do katalogu interfejsów API.
- Kliknij kartę Interfejsy API, jeśli nie jest jeszcze wybrana.
- Kliknij wiersz interfejsu API, który chcesz edytować.
- Kliknij
Edytuj. - W sekcji Szczegóły interfejsu API zaznacz lub odznacz pole wyboru Wymagaj od programistów określania adresu URL wywołania zwrotnego.
- Kliknij Zapisz.
curl
W wywołaniu update
umieść jeden z tych elementów:
"requireCallbackUrl": true, # Portal user is required to input a URL "requireCallbackUrl": false, # Portal user is not required to input a URL
Aby edytować interfejs API:
-
curl -X GET "https://api.enterprise.apigee.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC" \ -H "Authorization: Bearer ACCESS_TOKEN" Aby edytować interfejs API, użyj wywołania update. Uwzględnij zmienne wartości, które chcesz zachować, i zmień wartości, które chcesz zmienić. Jeśli pominiesz ustawienie podlegające zmianom, używana jest wartość domyślna.
curl -X PUT "https://api.enterprise.apigee.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC" \ -H "Authorization: Bearer ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "title": "TITLE", "description": "DESCRIPTION", "anonAllowed": ANON_TRUE_OR_FALSE, "imageUrl": IMAGE_URL, "requireCallbackUrl": CALLBACK_TRUE_OR_FALSE, "categoryIds": [ "CATEGORY_ID1", "CATEGORY_ID2" ], "published": PUBLISHED_TRUE_OR_FALSE }'
Szczegółowy przykład czynności, zmiennych i zwracanego ładunku znajdziesz w artykule Edytowanie interfejsu API.
Zarządzanie obrazem karty interfejsu API
Zarządzaj obrazem, który pojawia się na karcie interfejsu API na stronie interfejsów API, dodając lub zmieniając bieżący obraz.
Aby zarządzać obrazem na karcie interfejsu API, użyj interfejsu lub polecenia curl:
UI
Aby zarządzać obrazem na karcie interfejsu API:
- Uzyskaj dostęp do katalogu interfejsów API.
- Kliknij kartę Interfejsy API, jeśli nie jest jeszcze wybrana.
- Kliknij wiersz interfejsu API, który chcesz edytować.
- Kliknij
Edytuj. W sekcji Szczegóły interfejsu API:
- Jeśli nie wybrano obrazu, kliknij Wybierz obraz, aby wskazać lub przesłać obraz.
- Aby określić lub przesłać inny obraz, kliknij Zmień obraz.
- Aby usunąć obraz, kliknij x na obrazie.
Podczas określania obrazu podaj obraz z zewnętrznym adresem URL używanym w przypadku produktu w katalogu lub ścieżkę do plików obrazów przechowywanych w portalu, np.
/files/book-tree.jpg. Jeśli podasz adres URL zewnętrznego obrazu, nie zostanie on przesłany do Twoich komponentów. Ponadto wczytywanie obrazu w zintegrowanym portalu będzie zależeć od jego dostępności, która może być blokowana lub ograniczana przez zasady bezpieczeństwa treści.Kliknij Zapisz.
curl
W wywołaniu update
uwzględnij te elementy:
# Omit line for no image file "imageUrl": "IMAGE_URL" # URL of the external image or name of the image file
Aby edytować interfejs API:
-
curl -X GET "https://api.enterprise.apigee.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC" \ -H "Authorization: Bearer ACCESS_TOKEN" Aby edytować interfejs API, użyj wywołania update. Uwzględnij zmienne wartości, które chcesz zachować, i zmień wartości, które chcesz zmienić. Jeśli pominiesz ustawienie podlegające zmianom, używana jest wartość domyślna.
curl -X PUT "https://api.enterprise.apigee.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC" \ -H "Authorization: Bearer ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "title": "TITLE", "description": "DESCRIPTION", "anonAllowed": ANON_TRUE_OR_FALSE, "imageUrl": IMAGE_URL, "requireCallbackUrl": CALLBACK_TRUE_OR_FALSE, "categoryIds": [ "CATEGORY_ID1", "CATEGORY_ID2" ], "published": PUBLISHED_TRUE_OR_FALSE }'
Szczegółowy przykład czynności, zmiennych i zwracanego ładunku znajdziesz w artykule Edytowanie interfejsu API.
Tagowanie interfejsu API za pomocą kategorii
Korzystanie z kategorii pomaga deweloperom aplikacji odkrywać powiązane interfejsy API. Zobacz też Zarządzanie kategoriami.
Otaguj interfejs API za pomocą kategorii w jeden z tych sposobów:
- Podczas edytowania interfejsu API możesz zarządzać kategoriami, do których jest on przypisany, zgodnie z opisem poniżej.
- Zarządzaj interfejsami API przypisanymi do kategorii podczas edytowania kategorii.
Aby otagować interfejs API za pomocą kategorii, użyj interfejsu lub polecenia curl:
UI
Aby przypisać interfejs API do kategorii podczas jego edytowania:
- Uzyskaj dostęp do katalogu interfejsów API.
- Kliknij kartę Interfejsy API, jeśli nie jest jeszcze wybrana.
- Kliknij wiersz interfejsu API, który chcesz edytować.
- Kliknij
Edytuj. - Kliknij pole Kategorie i wykonaj jedną z tych czynności:
- Wybierz kategorię z listy.
- Dodaj nową kategorię, wpisując jej nazwę i naciskając Enter. Nowa kategoria zostanie dodana do strony Kategorie i będzie dostępna podczas dodawania lub edytowania innych interfejsów API.
- Powtórz tę czynność, aby przypisać interfejs API do większej liczby kategorii.
- Kliknij Zapisz.
curl
W wywołaniu update
uwzględnij te elementy:
# Omit line for no categories "categoryIds": [ "CATEGORY_ID1", # A category ID number "CATEGORY_ID2" # A category ID number ],
Użyj polecenia list categories (wyświetl kategorie), aby uzyskać numery identyfikatorów kategorii.
Aby edytować interfejs API:
-
curl -X GET "https://api.enterprise.apigee.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC" \ -H "Authorization: Bearer ACCESS_TOKEN" Aby edytować interfejs API, użyj wywołania update. Uwzględnij zmienne wartości, które chcesz zachować, i zmień wartości, które chcesz zmienić. Jeśli pominiesz ustawienie podlegające zmianom, używana jest wartość domyślna.
curl -X PUT "https://api.enterprise.apigee.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC" \ -H "Authorization: Bearer ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "title": "TITLE", "description": "DESCRIPTION", "anonAllowed": ANON_TRUE_OR_FALSE, "imageUrl": IMAGE_URL, "requireCallbackUrl": CALLBACK_TRUE_OR_FALSE, "categoryIds": [ "CATEGORY_ID1", "CATEGORY_ID2" ], "published": PUBLISHED_TRUE_OR_FALSE }'
Szczegółowy przykład czynności, zmiennych i zwracanego ładunku znajdziesz w artykule Edytowanie interfejsu API.
Edytowanie wyświetlanego tytułu i opisu
Aby edytować tytuł i opis wyświetlania, użyj interfejsu lub polecenia curl:
UI
Aby edytować wyświetlaną nazwę i opis:
- Uzyskaj dostęp do katalogu interfejsów API.
- Kliknij kartę Interfejsy API, jeśli nie jest jeszcze wybrana.
- Kliknij wiersz interfejsu API, który chcesz edytować.
- Kliknij
Edytuj. - W razie potrzeby zmień pola Wyświetlany tytuł i Wyświetlany opis.
- Kliknij Zapisz.
curl
W wywołaniu update
uwzględnij te elementy:
"title": "TITLE", # Display title "description": "DESCRIPTION", # Display description
Aby edytować interfejs API:
-
curl -X GET "https://api.enterprise.apigee.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC" \ -H "Authorization: Bearer ACCESS_TOKEN" Aby edytować interfejs API, użyj wywołania update. Uwzględnij zmienne wartości, które chcesz zachować, i zmień wartości, które chcesz zmienić. Jeśli pominiesz ustawienie podlegające zmianom, używana jest wartość domyślna.
curl -X PUT "https://api.enterprise.apigee.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC" \ -H "Authorization: Bearer ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "title": "TITLE", "description": "DESCRIPTION", "anonAllowed": ANON_TRUE_OR_FALSE, "imageUrl": IMAGE_URL, "requireCallbackUrl": CALLBACK_TRUE_OR_FALSE, "categoryIds": [ "CATEGORY_ID1", "CATEGORY_ID2" ], "published": PUBLISHED_TRUE_OR_FALSE }'
Szczegółowy przykład czynności, zmiennych i zwracanego ładunku znajdziesz w artykule Edytowanie interfejsu API.
Usuwanie interfejsu API z portalu
Aby usunąć interfejs API z portalu, użyj interfejsu lub polecenia curl:
UI
Aby usunąć interfejs API z portalu:
- Uzyskaj dostęp do katalogu interfejsów API.
- Wybierz Interfejsy API, jeśli nie są jeszcze wybrane.
- Umieść kursor nad interfejsem API na liście, aby wyświetlić menu działań.
- Kliknij
Usuń.
curl
Aby usunąć interfejs API z portalu:
curl -X DELETE "https://api.enterprise.apigee.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC" \
-H "Authorization: Bearer ACCESS_TOKEN"
Zastąp następujące elementy:
-
ORG_NAME nazwą organizacji. Na przykład:
my-org. -
SITE_ID z nazwą portalu w formacie ORG_NAME-PORTAL_NAME, gdzie ORG_NAME to nazwa organizacji, a PORTAL_NAME to nazwa portalu przekonwertowana na małe litery z usuniętymi spacjami i myślnikami. Na przykład:
my-org-myportal. -
API_DOC z wygenerowanym
iddokumentu. Na przykład:399668. Aby znaleźć tę wartość, użyj polecenia list API docs (lista dokumentów interfejsu API). - ACCESS_TOKEN z tokenem uwierzytelniania używanym do uzyskiwania dostępu do interfejsu Apigee Edge API. Więcej informacji o uwierzytelnianiu i tokenach znajdziesz w artykule Uwierzytelnianie dostępu do interfejsu Edge API.
Ładunek odpowiedzi:
{ "status": "success", "message": "Apidoc deleted", "data": { }, "code": null, "request_id": "1790036484", "error_code": null }
Zarządzanie dokumentacją API
W sekcjach poniżej znajdziesz informacje o tym, jak aktualizować, pobierać i usuwać dokumentację interfejsu API.
Dokumentacja interfejsu Update API
Aby przesłać inną wersję dokumentacji API:
UI
- Uzyskaj dostęp do katalogu interfejsów API.
- Kliknij kartę Interfejsy API, jeśli nie jest jeszcze wybrana.
- Kliknij wiersz interfejsu API, który chcesz edytować.
- Sprawdź stan zrzutu.
Jeśli jest nieaktualny, wyświetli się ten komunikat:

- Kliknij Edytuj.
- Wykonaj jedną z tych czynności:
- Aby odświeżyć nieaktualny zrzut dokumentu OpenAPI, kliknij Odśwież zrzut.
- Aby zmienić dokument używany do generowania dokumentacji API, w sekcji Dokumentacja API kliknij Wybierz dokument i wybierz nowy dokument.
- W panelu dokumentacja interfejsu API wybierz jedną z tych opcji:
- Dokument OpenAPI
- Schemat GraphQL
- Kliknij Wybierz dokument i wybierz najnowszą wersję dokumentu.
- W przypadku GraphQL podaj URL punktu końcowego.
- Kliknij Zapisz.
Dokumentacja API jest renderowana z dokumentu i dodawana do strony Dokumentacja API. Stan zrzutu zostanie zaktualizowany do bieżącego:

curl
Aby zaktualizować zawartość dokumentacji OpenAPI lub GraphQL:
OpenAPI
curl -X PATCH "https://api.enterprise.apigee.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC/documentation" \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{"oasDocumentation": {
"spec":{ "displayName":"DISPLAY_NAME",
"contents":"CONTENTS"}
}
}'
Zastąp następujące elementy:
-
ORG_NAME nazwą organizacji. Na przykład:
my-org. -
SITE_ID z nazwą portalu w formacie ORG_NAME-PORTAL_NAME, gdzie ORG_NAME to nazwa organizacji, a PORTAL_NAME to nazwa portalu przekonwertowana na małe litery z usuniętymi spacjami i myślnikami. Na przykład:
my-org-myportal. -
API_DOC z wygenerowanym
iddokumentu. Na przykład:399668. Aby znaleźć tę wartość, użyj polecenia list API docs (lista dokumentów interfejsu API). -
DISPLAY_NAME z wyświetlaną nazwą dokumentacji API. Na przykład:
Hello World 2. - CONTENTS z ciągiem tekstowym zakodowanym w formacie base64, który zawiera dokumentację interfejsu API. Większość środowisk deweloperskich zawiera narzędzie do konwersji base64. Dostępnych jest też wiele narzędzi do konwersji online.
Ładunek odpowiedzi:
{ "status":"success", "message":"Api documentation updated", "requestId":"645138278" "data": { "oasDocumentation": { "spec": { "displayName": "Hello World 2" }, "Format": "YAML" } } }
GraphQL
curl -X PATCH "https://api.enterprise.apigee.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC/documentation" \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{"graphqlDocumentation": {
"schema":{"displayName":"DISPLAY_NAME",
"contents":"CONTENTS"},
"endpointUri": "ENDPOINT_URI"
}
}'
Zastąp następujące elementy:
-
ORG_NAME nazwą organizacji. Na przykład:
my-org. -
SITE_ID z nazwą portalu w formacie ORG_NAME-PORTAL_NAME, gdzie ORG_NAME to nazwa organizacji, a PORTAL_NAME to nazwa portalu przekonwertowana na małe litery z usuniętymi spacjami i myślnikami. Na przykład:
my-org-myportal. -
API_DOC z wygenerowanym
iddokumentu. Na przykład:399668. Aby znaleźć tę wartość, użyj polecenia list API docs (lista dokumentów interfejsu API). -
DISPLAY_NAME z wyświetlaną nazwą dokumentacji API. Na przykład:
Hello World 2. -
ENDPOINT_URI nazwą domeny identyfikatora URI punktu końcowego. Na przykład:
https://demo.google.com/graphql. - CONTENTS z ciągiem tekstowym zakodowanym w formacie base64, który zawiera dokumentację interfejsu API. Większość środowisk deweloperskich zawiera narzędzie do konwersji base64. Dostępnych jest też wiele narzędzi do konwersji online.
Ładunek odpowiedzi:
{ "status": "success", "message": "ApiDocDocumentation updated", "data": { "oasDocumentation": null, "graphqlDocumentation": { "schema": { "displayName": "schema.docs.graphql", "contents": "" }, "endpointUri": "https://demo.google.com/graphql" } }, "code": null, "request_id": "640336173", "error_code": null }
Dokumentacja interfejsu API jest renderowana z dokumentu i dodawana do strony interfejsów API w aktywnym portalu.
Pobieranie dokumentacji API
Aby pobrać dokumentację API:
UI
curl
Aby pobrać dokumentację API za pomocą polecenia get documentation:
curl -X GET "https://api.enterprise.apigee.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC/documentation" \
-H "Authorization: Bearer ACCESS_TOKEN"
Zastąp następujące elementy:
-
ORG_NAME nazwą organizacji. Na przykład:
my-org. -
SITE_ID z nazwą portalu w formacie ORG_NAME-PORTAL_NAME, gdzie ORG_NAME to nazwa organizacji, a PORTAL_NAME to nazwa portalu przekonwertowana na małe litery z usuniętymi spacjami i myślnikami. Na przykład:
my-org-myportal. API_DOC z wygenerowanym
iddokumentu. Na przykład:399668. Aby znaleźć tę wartość, użyj polecenia list API docs (lista dokumentów interfejsu API).Ładunek odpowiedzi:
{ "status": "success", "message": "ApiDocDocumentation returned", "data": { "oasDocumentation": { "spec": { "displayName": "mock", "contents": "b3BlbmFwaTogMy4wLjAKaW5mbzoKICBkZXNjcmlw ..." }, "format": "YAML" }, "graphqlDocumentation": null }, "code": null, "request_id": "269996898", "error_code": null }
Gdzie:
contents: ciąg znaków zakodowany w formacie base64, który zawiera dokumentację API.
Usuwanie dokumentacji API
Aby usunąć dokumentację API:
UI
- Uzyskaj dostęp do katalogu interfejsów API.
- Kliknij kartę Interfejsy API, jeśli nie jest jeszcze wybrana.
- Kliknij wiersz interfejsu API, który chcesz edytować.
- Kliknij Edytuj.
- W panelu dokumentacja API wybierz Brak dokumentacji.
- Kliknij Zapisz.
curl
Aby usunąć istniejące treści, użyj interfejsu API aktualizacji:
curl -X PATCH "https://api.enterprise.apigee.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC/documentation" \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{}'
Zastąp następujące elementy:
-
ORG_NAME nazwą organizacji. Na przykład:
my-org. -
SITE_ID z nazwą portalu w formacie ORG_NAME-PORTAL_NAME, gdzie ORG_NAME to nazwa organizacji, a PORTAL_NAME to nazwa portalu przekonwertowana na małe litery z usuniętymi spacjami i myślnikami. Na przykład:
my-org-myportal. -
API_DOC z wygenerowanym
iddokumentu. Na przykład:399668. Aby znaleźć tę wartość, użyj polecenia list API docs (lista dokumentów interfejsu API).
Ładunek odpowiedzi:
{ "status": "success", "message": "ApiDocDocumentation updated", "data": { "oasDocumentation": null, "graphqlDocumentation": null }, "code": null, "request_id": "304329676", "error_code": null }
Zarządzanie kategoriami używanymi do wykrywania powiązanych interfejsów API
Oznacz interfejs API za pomocą kategorii, aby umożliwić programistom aplikacji odkrywanie powiązanych interfejsów API na stronie interfejsów API w aktywnym portalu. Dodawaj kategoriami i zarządzaj nimi zgodnie z opisem w sekcjach poniżej.
Odkrywaj kategorie
Aby wyświetlić interfejsy API w portalu, użyj interfejsu lub polecenia curl.
UI
Aby wyświetlić stronę Kategorie:
- Kliknij Opublikuj > Portale i wybierz portal.
- Na stronie głównej portalu kliknij Katalog interfejsów API.
Możesz też wybrać Katalog interfejsów API w menu portalu w górnym pasku nawigacyjnym.
- Kliknij kartę Kategorie.
Na karcie Kategorie w katalogu interfejsów API wyświetla się lista kategorii zdefiniowanych w Twoim portalu.

Jak widać na poprzednim rysunku, strona Interfejsy API umożliwia:
- Wyświetlanie kategorii i interfejsów API, do których są przypisane
- Dodaj kategorię
- Edytowanie kategorii
- Usuwanie kategorii
- zarządzać interfejsami API opublikowanymi w portalu; Zobacz Przeglądanie katalogu interfejsów API
curl
Aby wyświetlić listę kategorii:
curl -X GET "https://api.enterprise.apigee.com/v1/organizations/ORG_NAME/sites/SITE_ID/apicategories" \
-H "Authorization: Bearer ACCESS_TOKEN"
Zastąp następujące elementy:
-
ORG_NAME nazwą organizacji. Na przykład:
my-org. -
SITE_ID z nazwą portalu w formacie ORG_NAME-PORTAL_NAME, gdzie ORG_NAME to nazwa organizacji, a PORTAL_NAME to nazwa portalu przekonwertowana na małe litery z usuniętymi spacjami i myślnikami. Na przykład:
my-org-myportal. - ACCESS_TOKEN z tokenem uwierzytelniania używanym do uzyskiwania dostępu do interfejsu Apigee Edge API. Więcej informacji o uwierzytelnianiu i tokenach znajdziesz w artykule Uwierzytelnianie dostępu do interfejsu Edge API.
Ładunek odpowiedzi:
{ "status": "success", "message": "all ApiCategory items returned", "data": [ { "id": "e0518597-ece2-4d7d-ba7c-d1793df0f8db", "siteId": "my-org-myportal", "name": "My Category" }, { "id": "61c1014c-89c9-40e6-be3c-69cca3505620", "siteId": "my-org-myportal", "name": "test2" } ], "code": null, "request_id": "1263510680", "error_code": null }
Gdzie:
-
id: identyfikator elementu kategorii. Na przykład:61c1014c-89c9-40e6-be3c-69cca3505620.
Dodawanie kategorii
Dodaj kategorię na jeden z tych sposobów:
- Wpisz nazwę kategorii podczas dodawania interfejsu API do portalu.
- Ręczne dodawanie kategorii (opis poniżej)
Nowa kategoria zostanie dodana do strony Kategorie i będzie dostępna podczas dodawania lub edytowania innych interfejsów API.
Aby dodać kategorię, użyj interfejsu lub polecenia curl:
UI
Aby dodać kategorię ręcznie:
- Otwórz stronę Kategorie.
- Kliknij + Dodaj.
- Wpisz nazwę nowej kategorii.
- Opcjonalnie możesz wybrać co najmniej 1 interfejs API, który chcesz przypisać do kategorii.
- Kliknij Utwórz.
curl
Aby dodać kategorię:
curl -X POST "https://api.enterprise.apigee.com/v1/organizations/ORG_NAME/sites/SITE_ID/apicategories" \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{"name": "CATEGORY_NAME" }'
Zastąp następujące elementy:
-
ORG_NAME nazwą organizacji. Na przykład:
my-org. -
SITE_ID z nazwą portalu w formacie ORG_NAME-PORTAL_NAME, gdzie ORG_NAME to nazwa organizacji, a PORTAL_NAME to nazwa portalu przekonwertowana na małe litery z usuniętymi spacjami i myślnikami. Na przykład:
my-org-myportal. - ACCESS_TOKEN z tokenem uwierzytelniania używanym do uzyskiwania dostępu do interfejsu Apigee Edge API. Więcej informacji o uwierzytelnianiu i tokenach znajdziesz w artykule Uwierzytelnianie dostępu do interfejsu Edge API.
-
CATEGORY_NAME z nazwą kategorii. Na przykład:
demo-backend.
Ładunek odpowiedzi:
{ "status": "success", "message": "API category created", "data": { "id": "61de810e-b48b-4cc1-8f22-959038aadcce", "siteId": "my-org-myportal", "name": "demo-backend" }, "code": null, "request_id": "363146927", "error_code": null }
Edytowanie kategorii
Aby edytować kategorię, użyj interfejsu lub polecenia curl:
UI
Aby edytować kategorię:
- Otwórz stronę Kategorie.
- Kliknij
Edytuj. - Edytuj nazwę kategorii.
- Dodawanie i usuwanie tagów API.
- Kliknij Zapisz.
curl
Aby edytować kategorię:
curl -X PATCH "https://api.enterprise.apigee.com/v1/organizations/ORG_NAME/sites/SITE_ID/apicategories/CATEGORY_ID" \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{"name": "CATEGORY_NAME" }'
Zastąp następujące elementy:
-
ORG_NAME nazwą organizacji. Na przykład:
my-org. -
SITE_ID z nazwą portalu w formacie ORG_NAME-PORTAL_NAME, gdzie ORG_NAME to nazwa organizacji, a PORTAL_NAME to nazwa portalu przekonwertowana na małe litery, z usuniętymi spacjami i myślnikami. Na przykład:
my-org-myportal. -
CATEGORY_ID z identyfikatorem kategorii. Na przykład:
bf6505eb-2a0f-47af-a00a-ded40ac72960. Kolejne identyfikatory kategorii oddziel przecinkami. Pobierz identyfikator kategorii za pomocą polecenia list API categories. - ACCESS_TOKEN z tokenem uwierzytelniania używanym do uzyskiwania dostępu do interfejsu Apigee Edge API. Więcej informacji o uwierzytelnianiu i tokenach znajdziesz w artykule Uwierzytelnianie dostępu do interfejsu Edge API.
-
CATEGORY_NAME z nazwą kategorii. Na przykład:
demo-backend.
Ładunek odpowiedzi:
{ "status": "success", "message": "ApiCategory updated", "data": { "id": "61de810e-b48b-4cc1-8f22-959038aadcce", "siteId": "my-org-myportal", "name": "demo-backend-test" }, "code": null, "request_id": "1976875617", "error_code": null }
Usuwanie kategorii
Gdy usuniesz kategorię, zostaną też usunięte wszystkie przypisane do niej tagi interfejsu API.
Aby usunąć kategorię, użyj interfejsu lub polecenia curl:
UI
Aby usunąć kategorię:
- Otwórz stronę Kategorie.
- Umieść kursor nad kategorią, którą chcesz edytować, aby wyświetlić menu działań.
- Kliknij
Usuń. - Kliknij Usuń, aby potwierdzić.
curl
Aby usunąć kategorię:
curl -X DELETE "https://api.enterprise.apigee.com/v1/organizations/ORG_NAME/sites/SITE_ID/apicategories/CATEGORY_ID" \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "Content-Type: application/json"
Zastąp następujące elementy:
-
ORG_NAME nazwą organizacji. Na przykład:
my-org. -
SITE_ID z nazwą portalu w formacie ORG_NAME-PORTAL_NAME, gdzie ORG_NAME to nazwa organizacji, a PORTAL_NAME to nazwa portalu przekonwertowana na małe litery, z usuniętymi spacjami i myślnikami. Na przykład:
my-org-myportal. -
CATEGORY_ID z identyfikatorem kategorii. Na przykład:
bf6505eb-2a0f-47af-a00a-ded40ac72960. Pobierz identyfikator kategorii za pomocą polecenia list API categories. - ACCESS_TOKEN z tokenem uwierzytelniania używanym do uzyskiwania dostępu do interfejsu Apigee Edge API. Więcej informacji o uwierzytelnianiu i tokenach znajdziesz w artykule Uwierzytelnianie dostępu do interfejsu Edge API.
Ładunek odpowiedzi:
{ "status": "success", "message": "ApiCategory deleted", "data": { }, "code": null, "request_id": "2032819627", "error_code": null }
Rozwiązywanie problemów z opublikowanymi interfejsami API
W kolejnych sekcjach znajdziesz informacje, które pomogą Ci rozwiązać konkretne błędy związane z naszymi opublikowanymi interfejsami API.
Błąd: podczas korzystania z opcji „Wypróbuj ten interfejs API” wystąpił błąd pobierania
Jeśli podczas korzystania z opcji Wypróbuj ten interfejs API 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
schemesw dokumencie OpenAPI przed HTTP podasz HTTPS. Na przykład:schemes: - https - httpW przypadku błędów ograniczeń związanych z mechanizmem CORS sprawdź, czy mechanizm CORS jest obsługiwany w Twoich serwerach proxy interfejsu API. CORS to standardowy mechanizm, który umożliwia żądania z innych domen po stronie klienta. Zobacz Konfigurowanie serwera proxy interfejsu API pod kątem obsługi funkcji „Wypróbuj ten interfejs API”.
Błąd: nagłówek „Access-Control-Allow-Origin” zawiera wiele wartości „*, *”, ale dozwolona jest tylko jedna
Podczas korzystania z opcji Wypróbuj ten interfejs API możesz zobaczyć ten komunikat o błędzie, jeśli nagłówek Access-Control-Allow-Origin już istnieje:
The Access-Control-Allow-Origin header contains multiple values '*, *', but only one is allowed.
Aby naprawić ten błąd, zmodyfikuj zasadę AssignMessage, aby używać <Set>
do ustawiania nagłówków CORS zamiast <Add>, jak pokazano w poniższym fragmencie.
Więcej informacji znajdziesz w artykule Błąd CORS : nagłówek zawiera wiele wartości „*, *”, ale dozwolona jest tylko jedna.
<AssignMessage async="false" continueOnError="false" enabled="true" name="add-cors"> <DisplayName>Add CORS</DisplayName> <FaultRules/> <Properties/> <Set> <Headers> <Header name="Access-Control-Allow-Origin">{request.header.origin}</Header> <Header name="Access-Control-Allow-Headers">origin, x-requested-with, accept, content-type, authorization</Header> <Header name="Access-Control-Max-Age">3628800</Header> <Header name="Access-Control-Allow-Methods">GET, PUT, POST, DELETE</Header> </Headers> </Set> <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables> <AssignTo createNew="false" transport="http" type="response"/> </AssignMessage>
Błąd: niedozwolone pole nagłówka żądania
Jeśli podczas korzystania z opcji Wypróbuj ten interfejs API pojawi się błąd Request header field not allowed podobny do tego poniżej, być może trzeba zaktualizować nagłówki obsługiwane w zasadach CORS. Na przykład:
Access to XMLHttpRequest ... has been blocked by CORS policy: Request header field content-type is not allowed by Access-Control-Allow-Headers in preflight response
W tym przykładzie musisz dodać nagłówek content-type do sekcji Access-Control-Allow-Headers w zasadach AssignMessage CORS, zgodnie z opisem w artykule
Dołączanie zasad Add CORS do nowego serwera proxy interfejsu API.
Błąd: odmowa dostępu podczas wywoływania serwera proxy interfejsu API za pomocą OAuth2
Zasady OAuthV2 Apigee zwracają odpowiedź tokena, która zawiera pewne właściwości niezgodne ze standardem RFC. Na przykład zasady zwrócą token o wartości BearerToken zamiast oczekiwanej wartości zgodnej z RFC Bearer.
Ta nieprawidłowa odpowiedź token_type może spowodować błąd Access denied podczas korzystania z funkcji Wypróbuj ten interfejs API.
Aby rozwiązać ten problem, możesz utworzyć zasadę JavaScript lub AssignMessage, która przekształci dane wyjściowe zasady w format zgodny z zasadami. Więcej informacji znajdziesz w artykule zachowanie niezgodne z RFC.