Tworzenie serwera proxy interfejsów API na podstawie specyfikacji OpenAPI | Apigee Edge

Z tego samouczka dowiesz się, jak utworzyć serwer proxy Edge API na podstawie specyfikacji OpenAPI za pomocą interfejsu zarządzania Apigee Edge. Po wywołaniu serwera proxy interfejsu API za pomocą klienta HTTP, takiego jak cURL, serwer proxy interfejsu API wysyła żądanie do makiety Apigee.

Informacje o inicjatywie Open API

„Open API Initiative (OAI) koncentruje się na tworzeniu, rozwijaniu i promowaniu dostawcy neutralnego formatu opisu interfejsu API na podstawie specyfikacji Swagger”. Więcej informacji o inicjatywie Open API Initiative znajdziesz na stronie https://openapis.org.

Specyfikacja OpenAPI używa standardowego formatu RESTowego API. Specyfikacja OpenAPI napisana w formacie JSON lub YAML jest czytelna dla komputera, ale zrozumiała dla człowieka. Specyfikacja opisuje takie elementy interfejsu API jako ścieżkę podstawową, ścieżki i czasowniki, nagłówki, parametry zapytania, operacje, typy treści, opisy odpowiedzi itd. Dodatkowo do tworzenia dokumentacji API często używa się specyfikacji OpenAPI.

Informacje o przykładowej usłudze Apigee

Pozorowana usługa Apigee używana w tym samouczku jest hostowana w Apigee i zwraca proste dane. Nie wymaga klucza interfejsu API ani tokena dostępu. Możesz uzyskać do niego dostęp w przeglądarce. Kliknij, aby wypróbować:

http://mocktarget.apigee.net

Usługa docelowa zwraca powitanie Hello, guest!

Aby uzyskać informacje o pełnym zestawie interfejsów API obsługiwanych przez przykładową usługę docelową, kliknij te elementy:

http://mocktarget.apigee.net/help

Czego potrzebujesz

Konto Apigee Edge. Jeśli nie masz konta, możesz się zarejestrować, postępując zgodnie z instrukcjami zawartymi w artykule Tworzenie konta Apigee Edge.
Specyfikacja OpenAPI. W tym samouczku będziesz używać mocktarget.yamlspecyfikacji OpenAPI opisującej pozorowaną usługę Apigee http://mocktarget.apigee.net. Więcej informacji: https://github.com/apigee/api-platform-samples/tree/master/default-proxies/helloworld/openapi.
cURL zainstalowany na Twoim komputerze, aby wykonywać wywołania interfejsu API z poziomu wiersza poleceń lub przeglądarki.

Tworzenie serwera proxy interfejsu API

Edge

Aby utworzyć serwer proxy interfejsów API na podstawie specyfikacji OpenAPI za pomocą interfejsu Edge:

Zaloguj się na https://apigee.com/edge.
W głównym oknie kliknij „Protokoły API”.
Możesz też wybrać Develop (Program) > API Proxies (Serwery interfejsów API) na pasku nawigacyjnym po lewej stronie.
Kliknij + Serwer proxy.
W kreatorze tworzenia proxy kliknij Użyj specyfikacji OpenAPI, aby wyświetlić szablon Odwrotnego serwera proxy (najczęstszy).
Kliknij Importuj z adresu URL i podaj te informacje:
- Adres URL specyfikacji OpenAPI: ścieżka do nieprzetworzonej treści z GitHuba dla specyfikacji OpenAPI w polu URL:
```
https://raw.githubusercontent.com/apigee/api-platform-samples/master/default-proxies/helloworld/openapi/mocktarget3.0.yaml
```
- Nazwa specyfikacji: nazwa specyfikacji OpenAPI, np. przykładowa strona docelowa.
  Ta nazwa służy do przechowywania specyfikacji OpenAPI w magazynie specyfikacji. Zobacz Zarządzanie specyfikacjami.

Kliknij Importuj.

Pojawi się strona Details (Szczegóły) w kreatorze tworzenia serwera proxy. Pola są wstępnie wypełniane na podstawie wartości zdefiniowanych w specyfikacji OpenAPI, jak pokazano poniżej

W tabeli poniżej znajdziesz domyślne wartości wstępnie uzupełniane za pomocą właściwości w specyfikacji OpenAPI. Fragment specyfikacji OpenAPI ilustrujący używane właściwości jest widoczny pod tabelą.

Pole	Opis	Domyślna
Nazwa	Nazwa serwera proxy interfejsu API. Przykład: `Mock-Target-API`.	Właściwość `title` ze specyfikacji OpenAPI ze spacjami zastąpionymi myślnikami
Ścieżka podstawowa	Komponent ścieżki jednoznacznie identyfikujący ten serwer proxy interfejsu API w organizacji. Publiczny adres URL tego serwera proxy interfejsów API składa się z nazwy Twojej organizacji, środowiska, w którym ten serwer proxy interfejsu API jest wdrożony, oraz z tej ścieżki podstawowej. Na przykład: `http://myorg-test.apigee.net/mock-target-api`	Treść pola Nazwa została zamieniona na małe litery
Description	Opis serwera proxy interfejsu API.	Właściwość `description` ze specyfikacji OpenAPI
Kierowanie (istniejący interfejs API)	Docelowy URL wywoływany w imieniu tego serwera proxy interfejsu API. Można użyć dowolnego adresu URL, który jest dostępny przez otwarty internet. Na przykład: `http://mocktarget.apigee.net`	Właściwość `servers` ze specyfikacji OpenAPI

Poniżej znajdziesz fragment specyfikacji OpenAPI zawierający właściwości służące do wstępnego wypełniania pól.

openapi: 3.0.0
info:
  description: OpenAPI Specification for the Apigee mock target service endpoint.
  version: 1.0.0
  title: Mock Target API
paths:
  /:
    get:
      summary: View personalized greeting
      operationId: View a personalized greeting
      description: View a personalized greeting for the specified or guest user.
      parameters:
        - name: user
          in: query
          description: Your user name.
          required: false
          schema:
            type: string
      responses:
        "200":
          description: Success
...
servers:
  - url: http://mocktarget.apigee.net
  - url: https://mocktarget.apigee.net
...

Edytuj pole Opis w ten sposób: API proxy for the Apigee mock target service endpoint.
Kliknij Dalej.
Na stronie Wspólne zasady w sekcji Zabezpieczenia: autoryzacja wybierz opcję Powodzenie (brak autoryzacji) i kliknij Dalej:
Na stronie Flows (Procesy) wybierz wszystkie operacje.
Wskazówka: przepływy warunkowe są generowane automatycznie na podstawie operacji zdefiniowanych w obiekcie paths w specyfikacji OpenAPI. Przepływy warunkowe informują Edge: „Gdy to zobaczysz, wykonaj tę logikę”. Jeśli na przykład wywołanie interfejsu API jest GET dla zasobu /xml (warunku), przekształć odpowiedź w JSON (za pomocą zasady dołączonej do przepływu warunkowego). W ramach każdej transakcji wykonywany jest tylko 1 przepływ – pierwszy, którego warunek przyjmuje wartość Prawda.
Kliknij Dalej.
Na stronie Hosty wirtualne wybierz domyślne i bezpieczne, a następnie kliknij Dalej.
Na stronie Podsumowanie w sekcji Opcjonalne wdrożenie wybierz środowisko Testowe i kliknij Utwórz i wdróż:

Apigee tworzy nowy serwer proxy interfejsu API i wdraża go w środowisku testowym:
Kliknij Edytuj serwer proxy, aby wyświetlić stronę Przegląd informacji o serwerze proxy interfejsu API.

Classic Edge (prywatna w chmurze)

Aby utworzyć serwer proxy interfejsów API na podstawie specyfikacji OpenAPI za pomocą interfejsu Classic Edge:

Zaloguj się na https://apigee.com/edge.
W głównym oknie kliknij „Protokoły API”.
Możesz też wybrać Develop (Program) > API Proxies (Serwery interfejsów API) na pasku nawigacyjnym po lewej stronie.
Kliknij + Serwer proxy.
W kreatorze tworzenia proxy wybierz Odwrotny serwer proxy (najczęstszy) i kliknij Użyj OpenAPI.
Kliknij Importuj z adresu URL, w polu URL wpisz nazwę specyfikacji OpenAPI i w polu URL wpisz ścieżkę do nieprzetworzonej treści dla specyfikacji OpenAPI:

https://raw.githubusercontent.com/apigee/api-platform-samples/master/default-proxies/helloworld/openapi/mocktarget.yaml
Kliknij Wybierz.

Kliknij Dalej.

Pojawi się strona Details (Szczegóły) w kreatorze tworzenia serwera proxy. Pola są wstępnie wypełniane na podstawie wartości zdefiniowanych w specyfikacji OpenAPI, jak widać na tym rysunku.

W tabeli poniżej znajdziesz domyślne wartości wstępnie uzupełniane za pomocą właściwości w specyfikacji OpenAPI. Fragment specyfikacji OpenAPI ilustrujący używane właściwości jest widoczny pod tabelą.

Pole	Opis	Domyślna
Nazwa serwera proxy	Nazwa serwera proxy interfejsu API. Przykład: `Mock-Target-API`.	Właściwość `title` ze specyfikacji OpenAPI ze spacjami zastąpionymi myślnikami
Ścieżka bazowa serwera proxy	Komponent ścieżki jednoznacznie identyfikujący ten serwer proxy interfejsu API w organizacji. Publiczny adres URL tego serwera proxy interfejsów API składa się z nazwy Twojej organizacji, środowiska, w którym ten serwer proxy interfejsu API jest wdrożony, oraz z tej ścieżki podstawowej. Na przykład: `http://myorg-test.apigee.net/mock-target-api`	Treść pola Nazwa została zamieniona na małe litery
Istniejący interfejs API	Docelowy URL wywoływany w imieniu tego serwera proxy interfejsu API. Można użyć dowolnego adresu URL, który jest dostępny przez otwarty internet. Na przykład: `http://mocktarget.apigee.net`	Właściwość `servers` ze specyfikacji OpenAPI
Description	Opis serwera proxy interfejsu API.	Właściwość `description` ze specyfikacji OpenAPI

Poniżej znajdziesz fragment specyfikacji OpenAPI zawierający właściwości służące do wstępnego wypełniania pól.

openapi: 3.0.0
info:
  description: OpenAPI Specification for the Apigee mock target service endpoint.
  version: 1.0.0
  title: Mock Target API
paths:
  /:
    get:
      summary: View personalized greeting
      operationId: View a personalized greeting
      description: View a personalized greeting for the specified or guest user.
      parameters:
        - name: user
          in: query
          description: Your user name.
          required: false
          schema:
            type: string
      responses:
        "200":
          description: Success
...
servers:
  - url: http://mocktarget.apigee.net
  - url: https://mocktarget.apigee.net
...

Edytuj pole Opis w ten sposób: API proxy for the Apigee mock target service endpoint.
Kliknij Dalej.
Na stronie Flows (Procesy) wybierz wszystkie operacje.
Wskazówka: przepływy warunkowe są generowane automatycznie na podstawie operacji zdefiniowanych w obiekcie paths w specyfikacji OpenAPI. Przepływy warunkowe informują Edge: „Gdy to zobaczysz, wykonaj tę logikę”. Jeśli na przykład wywołanie interfejsu API jest GET dla zasobu /xml (warunku), przekształć odpowiedź w JSON (za pomocą zasady dołączonej do przepływu warunkowego). W ramach każdej transakcji wykonywany jest tylko 1 przepływ – pierwszy, którego warunek przyjmuje wartość Prawda.
Kliknij Dalej.
Na stronie Bezpieczeństwo wybierz Brak przekazywania jako opcję zabezpieczeń i kliknij Dalej.
Na stronie Wirtualne hosty upewnij się, że wszystkie hosty wirtualne są wybrane, a następnie kliknij Dalej.
Na stronie kompilacji wybierz środowisko testowe i kliknij Utwórz i wdróż.
Na stronie Podsumowanie zobaczysz potwierdzenie, że nowy serwer proxy interfejsu API został utworzony i wdrożony w środowisku testowym.
Kliknij Wersja robocza interfejsu API, aby wyświetlić stronę Przegląd dotyczącą serwera proxy interfejsu API.

Gratulacje! Serwer proxy interfejsu API został utworzony na podstawie specyfikacji OpenAPI. Następnie przetestuj, jak to działa.

Testowanie serwera proxy interfejsu API

Interfejs API Mock-Target-API możesz przetestować za pomocą cURL lub przeglądarki.

W oknie terminala uruchom to polecenie cURL. Zastąp nazwę swojej organizacji w adresie URL.

curl http://<org_name>-test.apigee.net/mock-target-api

Odpowiedź

Powinna pojawić się taka odpowiedź:

Hello, Guest!

Doskonale! Udało Ci się utworzyć prosty serwer proxy interfejsu API ze specyfikacji OpenAPI i przetestować go.

Dodaj zasadę XML do JSON

Następnie dodaj zasadę XML do JSON do przepływu warunkowego Wyświetl odpowiedź XML wygenerowanego automatycznie podczas tworzenia serwera proxy interfejsu API ze specyfikacji OpenAPI. Zasada konwertuje odpowiedź XML docelowego na kod JSON.

Najpierw wywołaj interfejs API, aby móc porównywać wyniki z tymi uzyskanymi po dodaniu zasady. W oknie terminalu uruchom to polecenie cURL. Wywołujesz zasób /xml usługi docelowej, który natywnie zwraca prosty blok XML. Zastąp nazwę swojej organizacji w adresie URL.

curl http://<org_name>-test.apigee.net/mock-target-api/xml

Odpowiedź

Powinna pojawić się taka odpowiedź:

<root> 
  <city>San Jose</city> 
  <firstName>John</firstName> 
  <lastName>Doe</lastName> 
  <state>CA</state> 
</root>

Teraz zrobimy coś, co spowoduje konwersję odpowiedzi XML na JSON. Dodaj zasadę XML do JSON do przepływu warunkowego wyświetlania odpowiedzi XML na serwerze proxy interfejsu API.

W prawym górnym rogu strony Przegląd Mock-Target-API kliknij kartę Programowanie w interfejsie Edge.
W panelu po lewej stronie Navigator > Endpoint Endpoints ( Punkty końcowe serwera proxy) > kliknij domyślny przepływ Wyświetl odpowiedź XML.
Kliknij dolny przycisk +Krok odpowiadający odpowiedzi przepływu.

Otworzy się okno Dodaj krok, aby wyświetlić listę wszystkich zasad, które możesz dodać.
Przewiń do kategorii Zapośredniczenie i kliknij XML do JSON.
Zachowaj wartości domyślne w polach Nazwa wyświetlana i Nazwa.
Kliknij Dodaj. Zasada XML do JSON jest stosowana do odpowiedzi.
Kliknij Zapisz.

Po dodaniu zasad wywołaj ponownie interfejs API przy użyciu cURL. Zwróć uwagę, że nadal wywołujesz ten sam zasób /xml. Usługa docelowa zwraca blok kodu XML, ale zasada w proxy interfejsu API przekonwertuje odpowiedź na kod JSON. Wywołaj to:

curl http://<org_name>-test.apigee.net/mock-target-api/xml

Pamiętaj, że odpowiedź XML jest konwertowana na JSON:

{"root":{"city":"San Jose","firstName":"John","lastName":"Doe","state":"CA"}}

Gratulacje! Udało Ci się przetestować wykonanie zasady dodanej do przepływu warunkowego.