OpenAPI

API Gateway unterstützt APIs, die mit unterstützten Versionen der OpenAPI-Spezifikation beschrieben werden.

Sie können Ihre API mit einem öffentlich verfügbaren REST-Framework wie Django oder Jersey implementieren.

Sie beschreiben die API in einer YAML-Datei, die als OpenAPI-Dokument bezeichnet wird. Auf dieser Seite werden einige Vorteile von OpenAPI erläutert. Außerdem wird die Grundstruktur eines OpenAPI-Dokuments gezeigt und Sie erhalten zusätzliche Informationen für den Einstieg in OpenAPI.

Unterstützte OpenAPI-Versionen

API Gateway unterstützt die folgenden OpenAPI-Versionen:

  1. OpenAPI 2.0 (früher Swagger)
  2. OpenAPI 3.0.x

Offizielle Spezifikationen für jede Version sind bei der OpenAPI Initiative verfügbar.

Unterstützung von Patchversionen

Die OpenAPI-Spezifikation gibt an, dass Patch-Versionen (z.B. In Versionen wie 3.0.1 oder 3.0.2 werden nur Fehler behoben oder Klarstellungen vorgenommen. Es werden keine neuen Funktionen hinzugefügt. Daher unterstützt API Gateway alle Patch-Versionen von 3.0.

Terminologie

In der gesamten API Gateway-Dokumentation bezieht sich OpenAPI 3.x auf alle unterstützten OpenAPI 3-Versionen, wie unter Unterstützte OpenAPI-Versionen beschrieben.

Vorteile

Einer der Hauptvorteile von OpenAPI ist die Dokumentation. Sobald Sie ein OpenAPI-Dokument haben, das Ihre API beschreibt, können Sie eine Referenzdokumentation für diese generieren.

Die Verwendung von OpenAPI bietet noch weitere Vorteile. Beispiele:

  • Clientbibliotheken erstellen in Dutzenden Sprachen erstellen
  • Server-Stubs erstellen
  • Projekte nutzen, um die Konformität zu überprüfen und Beispiele zu generieren

Grundstruktur eines OpenAPI-Dokuments

Ein OpenAPI-Dokument beschreibt die Oberfläche Ihrer REST API und definiert folgende Daten:

  • den Namen und die Beschreibung der API
  • die individuellen Endunkte (Pfade) in der API
  • Die für Aufrufer verwendete Authentifizierungsmethode

Die Struktur Ihres OpenAPI-Dokuments hängt von der verwendeten OpenAPI-Version ab. In den folgenden Beispielen wird die Struktur von OpenAPI 2.0 und OpenAPI 3.x beschrieben.

OpenAPI 2.0

Sollten Sie mit OpenAPI noch nicht vertraut sein, werfen Sie einen Blick auf die Swagger-Grundstruktur. Dort finden Sie ein OpenAPI-Beispieldokument (auch als Swagger-Spezifikation bezeichnet) und eine kurze Erläuterung der einzelnen Abschnitte der Datei. Das folgende Beispiel veranschaulicht diese grundlegende Struktur:

swagger: "2.0"
info:
  title: API_ID optional-string
  description: "Get the name of an airport from its three-letter IATA code."
  version: "1.0.0"
host: DNS_NAME_OF_DEPLOYED_API
schemes:
  - "https"
paths:
  "/airportName":
    get:
      description: "Get the airport name for a given IATA code."
      operationId: "airportName"
      parameters:
        -
          name: iataCode
          in: query
          required: true
          type: string
      responses:
        200:
          description: "Success."
          schema:
            type: string
        400:
          description: "The IATA code is invalid or missing."

OpenAPI 3.x

Sollten Sie mit OpenAPI noch nicht vertraut sein, werfen Sie einen Blick auf die Swagger-Grundstruktur. Dort finden Sie ein OpenAPI-Beispieldokument. Außerdem werden die einzelnen Abschnitte der Datei erläutert. Das folgende Beispiel veranschaulicht diese grundlegende Struktur:

openapi: 3.0.4
info:
  title: API_ID optional-string
  description: Get the name of an airport from its three-letter IATA code
  version: 1.0.0
x-google-api-management:
  backend:
    BACKEND_NAME
      address: https://BACKEND_URL/airportNameGET
      pathTranslation: APPEND_PATH_TO_ADDRESS
      protocol: "http/1.1"
x-google-backend: BACKEND_NAME
paths:
  /airportName:
    get:
      summary: Get the airport name for a given IATA code
      operationId: airportName
      responses:
        '200':
          description: A successful response
          content:
            application/json:
              schema:
                type: string
      parameters:
        - name: iataCode
          in: query
          required: true
          schema:
            type: string

Zusätzlich zur Grundstruktur können Sie die Datei openapi.yaml für folgende Konfigurationen verwenden:

OpenAPI-Dokument erstellen

Abhängig von der verwendeten Sprache können Sie ggf. ein OpenAPI-Dokument generieren. Java bietet Open-Source-Projekte für Jersey und Spring, mit denen OpenAPI-Dokumente aus Annotationen generiert werden können. Außerdem gibt es ein Maven-Plug-in. Für Python- und Node-Entwickler könnte OpenAPI.Tools ein interessantes Projekt sein.

Die OpenAPI-Community arbeitet kontinuierlich an der Entwicklung von Tools, die Unterstützung beim Erstellen von OpenAPI-Dokumenten bieten (und diese in einigen Sprachen sogar automatisch generieren). Weitere Informationen finden Sie in der OpenAPI-Spezifikation.

Nächste Schritte