OpenAPI

API Gateway unterstützt APIs, die mit der OpenAPI-Spezifikation Version 2.0 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.

Vorteile

Einer der Hauptvorteile von OpenAPI ist die Dokumentation. Sobald Sie ein OpenAPI-Dokument haben, das Ihre API beschreibt, ist es einfach, eine Referenzdokumentation für diese zu erstellen.

Es gibt noch weitere Vorteile von OpenAPI. 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

Sollten Sie mit OpenAPI noch nicht vertraut sein, werfen Sie einen Blick auf die Website zur 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."

Zusätzlich zur Grundstruktur können Sie mit der Datei openapi.yaml Folgendes 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