API-Proxy aus einer OpenAPI-Spezifikation erstellen | Apigee Edge

In dieser Anleitung erfahren Sie, wie Sie mit der Apigee Edge-Verwaltungs-UI einen Edge API-Proxy aus einer OpenAPI-Spezifikation erstellen. Wenn Sie den API-Proxy mit einem HTTP-Client wie cURL aufrufen, sendet der API-Proxy die Anfrage an den Apigee-Testdienst.

Informationen zur Open API-Initiative

"Die Open API-Initiative (OAI) konzentriert sich auf das Erstellen, Entwickeln und Bewerben eines neutralen API-Beschreibungsformats basierend auf der Swagger-Spezifikation". Weitere Informationen zur Open API-Initiative finden Sie unter https://openapis.org.

Eine OpenAPI-Spezifikation verwendet ein Standardformat, um eine RESTful API zu beschreiben. Eine OpenAPI-Spezifikation, im JSON- oder YAML-Format geschrieben, ist maschinenlesbar, aber auch für Nutzer leicht lesbar. In der Spezifikation werden solche Elemente einer API als Basispfad, Pfade und Verben, Header, Abfrageparameter, Vorgänge, Inhaltstypen, Antwortbeschreibungen usw. beschrieben. Außerdem wird eine OpenAPI-Spezifikation häufig zum Generieren einer API-Dokumentation verwendet.

Apigee-Zieldienst

Der in dieser Anleitung verwendete Apigee-Mock-Target-Dienst wird bei Apigee gehostet und gibt einfache Daten zurück. Ein API-Schlüssel oder ein Zugriffstoken sind nicht erforderlich. Sie können sogar über einen Webbrowser darauf zugreifen. Klicken Sie zum Testen auf folgenden Link:

http://mocktarget.apigee.net

Der Zieldienst gibt die Begrüßung Hello, guest! zurück.

Informationen zu den vollständigen APIs, die der simulierte Zieldienst unterstützt, finden Sie unter den folgenden Links:

http://mocktarget.apigee.net/help

Voraussetzungen

Ein Apigee Edge-Konto. Wenn Sie noch kein Konto haben, können Sie sich wie unter Apigee Edge-Konto erstellen beschrieben registrieren.
Eine OpenAPI-Spezifikation. In dieser Anleitung verwenden Sie die OpenAPI-Spezifikation mocktarget.yaml, in der der Apigee-Zieldienst http://mocktarget.apigee.net beschrieben ist. Weitere Informationen finden Sie unter https://github.com/apigee/api-platform-samples/tree/master/default-proxies/helloworld/openapi.
Sie müssen cURL auf Ihrem Computer installiert haben, um API-Aufrufe über die Befehlszeile auszuführen. oder in einem Webbrowser.

API-Proxy erstellen

Edge

So erstellen Sie den API-Proxy aus einer OpenAPI-Spezifikation mithilfe der Edge-Benutzeroberfläche:

Melden Sie sich unter https://apigee.com/edge an.
Klicken Sie im Hauptfenster auf API-Proxys.
Alternativ können Sie in der linken Navigationsleiste Entwickeln > API-Proxies auswählen.
Klicken Sie auf + Proxy.
Klicken Sie im Assistenten zum Erstellen eines Proxys auf OpenAPI-Spezifikation verwenden für die Vorlage Reverse-Proxy (am gängigsten).
Klicken Sie auf Aus URL importieren und geben Sie die folgenden Informationen ein:
- URL der OpenAPI-Spezifikation: Pfad zum Rohdateninhalt auf GitHub für die OpenAPI-Spezifikation im Feld URL:
```
https://raw.githubusercontent.com/apigee/api-platform-samples/master/default-proxies/helloworld/openapi/mocktarget3.0.yaml
```
- Spec name: Name der OpenAPI-Spezifikation, z. B. Mock Target.
  Dieser Name wird zum Speichern der OpenAPI-Spezifikation im Spezifikationsspeicher verwendet. Weitere Informationen finden Sie unter Spezifikationen verwalten.

Klicken Sie auf Importieren.

Die Seite "Details" im Assistenten "Create Proxy" wird angezeigt. Die Felder sind mit Werten gefüllt, die in der OpenAPI-Spezifikation definiert sind, wie im Folgenden gezeigt.

In der folgenden Tabelle werden die Standardwerte beschrieben, die mit Attributen in der OpenAPI-Spezifikation bereits ausgefüllt sind. Im Anschluss an die Tabelle finden Sie einen Auszug aus der OpenAPI-Spezifikation, der die verwendeten Eigenschaften veranschaulicht.

Feld	Beschreibung	Standard
Name	Name des API-Proxys. Beispiel: `Mock-Target-API`.	`title` aus der OpenAPI-Spezifikation, wobei Leerzeichen durch Bindestriche ersetzt werden.
Basispfad	Pfadkomponente, die diesen API-Proxy in der Organisation eindeutig identifiziert. Die öffentliche URL dieses API-Proxys besteht aus dem Namen Ihrer Organisation, einer Umgebung, in der dieser API-Proxy bereitgestellt wird, und diesem Basispfad. Beispiel: `http://myorg-test.apigee.net/mock-target-api`	Inhalt des Feldes Name wird in Kleinbuchstaben umgewandelt.
Beschreibung	Beschreibung des API-Proxys.	Attribut `description` aus der OpenAPI-Spezifikation.
Ziel (vorhandene API)	Die Ziel-URL, die im Namen dieses API-Proxys aufgerufen wird. Jede URL, auf die über das offene Internet zugegriffen werden kann, kann verwendet werden. Beispiel: `http://mocktarget.apigee.net`	Attribut `servers` aus der OpenAPI-Spezifikation.

Im Folgenden finden Sie einen Auszug aus der OpenAPI-Spezifikation mit den Attributen, die zum Vorausfüllen der Felder verwendet werden.

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
...

Bearbeiten Sie das Feld Beschreibung so: API proxy for the Apigee mock target service endpoint.
Klicken Sie auf Weiter.
Achten Sie darauf, dass auf der Seite Allgemeine Richtlinien unter „Sicherheit: Autorisierung“ die Option Pass through (no authorization) ausgewählt ist. Klicken Sie dann auf Weiter:
Prüfen Sie auf der Seite "Flows", ob alle Vorgänge ausgewählt sind.
Tipp: Bedingte Abläufe werden automatisch aus den Vorgängen generiert, die im Objekt paths in der OpenAPI-Spezifikation definiert sind. Durch bedingte Abläufe wird Edge mitgeteilt: ""Wenn diese Meldung angezeigt wird, führe diese Logik aus." Wenn ein API-Aufruf beispielsweise ein GET-Vorgang für die Ressource /xml ist (die Bedingung), wandeln Sie die Antwort in JSON um (über eine Richtlinie, die an den bedingten Ablauf angehängt ist). Nur ein Ablauf wird pro Transaktion ausgeführt: der erste Ablauf, dessen Bedingung als wahr ausgewertet wird.
Klicken Sie auf Weiter.
Wählen Sie auf der Seite Virtuelle Hosts die Optionen Standard und Sicher aus und klicken Sie auf Weiter.
Prüfen Sie auf der Seite Zusammenfassung, ob unter Optionale Bereitstellung die Testumgebung ausgewählt ist. Klicken Sie dann auf Erstellen und bereitstellen:

Apigee erstellt den neuen API-Proxy und stellt ihn in Ihrer Testumgebung bereit:
Klicken Sie auf Proxy bearbeiten, um die Übersichtsseite für den API-Proxy aufzurufen.

Classic Edge (Private Cloud)

So erstellen Sie den API-Proxy aus einer OpenAPI-Spezifikation mithilfe der Classic Edge-Benutzeroberfläche:

Melden Sie sich unter https://apigee.com/edge an.
Klicken Sie im Hauptfenster auf API-Proxys.
Alternativ können Sie in der linken Navigationsleiste Entwickeln > API-Proxies auswählen.
Klicken Sie auf + Proxy.
Wählen Sie im Assistenten zum Erstellen des Proxys die Option Reverse-Proxy (am gängigsten) aus und klicken Sie auf OpenAPI verwenden.
Klicken Sie auf Aus einer URL importieren, geben Sie einen Namen für die OpenAPI-Spezifikation ein und geben Sie im Feld URL den Pfad zum Rohdateninhalt auf GitHub für die OpenAPI-Spezifikation ein:

https://raw.githubusercontent.com/apigee/api-platform-samples/master/default-proxies/helloworld/openapi/mocktarget.yaml
Klicken Sie auf Auswählen.

Klicken Sie auf Weiter.

Die Seite "Details" im Assistenten "Create Proxy" wird angezeigt. Die Felder werden vorab mit Werten ausgefüllt, die in der OpenAPI-Spezifikation definiert sind (siehe folgende Abbildung).

In der folgenden Tabelle werden die Standardwerte beschrieben, die mit Attributen in der OpenAPI-Spezifikation bereits ausgefüllt sind. Im Anschluss an die Tabelle finden Sie einen Auszug aus der OpenAPI-Spezifikation, der die verwendeten Eigenschaften veranschaulicht.

Feld	Beschreibung	Standard
Proxy-Name	Name des API-Proxys. Beispiel: `Mock-Target-API`.	`title` aus der OpenAPI-Spezifikation, wobei Leerzeichen durch Bindestriche ersetzt werden.
Proxy-Basispfad	Pfadkomponente, die diesen API-Proxy in der Organisation eindeutig identifiziert. Die öffentliche URL dieses API-Proxys besteht aus dem Namen Ihrer Organisation, einer Umgebung, in der dieser API-Proxy bereitgestellt wird, und diesem Basispfad. Beispiel: `http://myorg-test.apigee.net/mock-target-api`	Inhalt des Feldes Name wird in Kleinbuchstaben umgewandelt.
Vorhandene API	Die Ziel-URL, die im Namen dieses API-Proxys aufgerufen wird. Jede URL, auf die über das offene Internet zugegriffen werden kann, kann verwendet werden. Beispiel: `http://mocktarget.apigee.net`	Attribut `servers` aus der OpenAPI-Spezifikation.
Beschreibung	Beschreibung des API-Proxys.	Attribut `description` aus der OpenAPI-Spezifikation.

Im Folgenden finden Sie einen Auszug aus der OpenAPI-Spezifikation mit den Attributen, die zum Vorausfüllen der Felder verwendet werden.

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
...

Bearbeiten Sie das Feld Beschreibung so: API proxy for the Apigee mock target service endpoint.
Klicken Sie auf Weiter.
Prüfen Sie auf der Seite "Flows", ob alle Vorgänge ausgewählt sind.
Tipp: Bedingte Abläufe werden automatisch aus den Vorgängen generiert, die im Objekt paths in der OpenAPI-Spezifikation definiert sind. Durch bedingte Abläufe wird Edge mitgeteilt: ""Wenn diese Meldung angezeigt wird, führe diese Logik aus." Wenn ein API-Aufruf beispielsweise ein GET-Vorgang für die Ressource /xml ist (die Bedingung), wandeln Sie die Antwort in JSON um (über eine Richtlinie, die an den bedingten Ablauf angehängt ist). Nur ein Ablauf wird pro Transaktion ausgeführt: der erste Ablauf, dessen Bedingung als wahr ausgewertet wird.
Klicken Sie auf Weiter.
Wählen Sie auf der Seite „Sicherheit“ die Sicherheitsoption Passthrough (none) aus und klicken Sie auf Weiter.
Prüfen Sie auf der Seite „Virtuelle Hosts“, ob alle virtuellen Hosts ausgewählt sind, und klicken Sie auf Weiter.
Achten Sie darauf, dass auf der Seite „Build“ die Umgebung Test ausgewählt ist. Klicken Sie dann auf Erstellen und Bereitstellen.
Auf der Übersichtsseite wird die Bestätigung angezeigt, dass der neue API-Proxy erfolgreich erstellt und in Ihrer Testumgebung bereitgestellt wurde.
Klicken Sie auf Mock-Target-API, um die Übersichtsseite für den API-Proxy aufzurufen.

Glückwunsch! Sie haben einen API-Proxy aus einer OpenAPI-Spezifikation erstellt. Als Nächstes testen Sie, wie er funktioniert.

API-Proxy testen

Sie können Ihre Mock-Target-API API mit cURL oder einem Webbrowser testen.

Führen Sie in einem Terminalfenster den folgenden cURL-Befehl aus. Ersetzen Sie den Namen Ihrer Organisation in der URL.

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

Antwort

Sie sollten die folgende Antwort sehen:

Hello, Guest!

Gut gemacht! Sie haben einen einfachen API-Proxy aus einer OpenAPI-Spezifikation erstellt und getestet.

"XML-to-JSON"-Richtlinie hinzufügen

Als Nächstes fügen Sie die "XML-to-JSON"-Richtlinie dem bedingten Ablauf View XML Response hinzu, der automatisch generiert wurde, als Sie den API-Proxy aus der OpenAPI-Spezifikation erstellt haben. Die Richtlinie konvertiert die XML-Antwort des Ziels in eine JSON-Antwort.

Rufen Sie zuerst die API auf, damit Sie die Ergebnisse mit denen vergleichen können, die Sie nach Hinzufügen der Richtlinie erhalten haben. Führen Sie in einem Terminalfenster den folgenden cURL-Befehl aus. Sie rufen die Ressource /xml des Zieldienstes auf, die nativ einen einfachen XML-Block zurückgibt. Ersetzen Sie die URL durch Ihren Organisationsnamen.

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

Antwort

Sie sollten die folgende Antwort sehen:

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

Jetzt wird die XML-Antwort in JSON konvertiert. Fügen Sie die "XML-to-JSON"-Richtlinie dem bedingten Ablauf "View XML Response" im API-Proxy hinzu.

Klicken Sie in der Edge-Benutzeroberfläche in der oberen rechten Ecke der Übersichtsseite der Mock-Target-API auf den Tab Develop.
Klicken Sie im linken Navigator unter „Proxyendpunkte“ > „Standard“ auf den bedingten Ablauf XML-Antwort ansehen.
Klicken Sie auf die Schaltfläche +Step, die der Antwort für den Ablauf entspricht.

Im Dialogfeld "Add step" wird eine Kategorienliste aller Richtlinien angezeigt, die Sie hinzufügen können.
Scrollen Sie zur Kategorie „Vermittlung“ und wählen Sie XML zu JSON aus.
Behalten Sie die Standardwerte für Display name und Name bei.
Klicken Sie auf Hinzufügen. Die "XML-to-JSON"-Richtlinie wird auf die Antwort angewendet.
Klicken Sie auf Speichern.

Rufen Sie nun die API mit cURL noch einmal auf. Beachten Sie, dass Sie immer noch dieselbe /xml-Ressource aufrufen. Der Zieldienst gibt weiterhin seinen XML-Block zurück, die Richtlinie im API-Proxy wird aber nun in die JSON-Antwort konvertiert. Führen Sie folgenden Aufruf aus:

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

Die XML-Antwort wird in das JSON-Format konvertiert:

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

Glückwunsch! Sie haben erfolgreich die Ausführung einer Richtlinie getestet, die einem bedingten Ablauf hinzugefügt wurde.