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
  3. OpenAPI 3.1.x

Die offiziellen Spezifikationen für jede Version sind von der OpenAPI Initiative verfügbar.

Unterstützung von Patchversionen

Die OpenAPI-Spezifikation gibt an, dass Patchversionen (z.B. 3.0.1, 3.0.2) nur Fehlerbehebungen oder Klarstellungen enthalten und keine neuen Funktionen hinzufügen. Daher unterstützt API Gateway alle Patchversionen von 3.0 und 3.1.

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 über ein OpenAPI-Dokument verfügen, das Ihre API beschreibt, können Sie eine Referenzdokumentation für diese erstellen.

Es gibt 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 Grundstruktur:

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 und eine Erläuterung der einzelnen Abschnitte der Datei. Das folgende Beispiel veranschaulicht diese Grundstruktur:

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:
  backends:
    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 verwenden, um Folgendes zu konfigurieren:

OpenAPI-Dokumente 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