OpenAPI

Cloud Endpoints 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 JSON- oder 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

Cloud Endpoints 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 Cloud Endpoints alle Patchversionen von 3.0.

Terminologie

In der gesamten Cloud Endpoints-Dokumentation bezieht sich OpenAPI 3.x auf alle unterstützten OpenAPI 3-Versionen.

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.

Außerdem können Sie mit OpenAPI:

  • Clientbibliotheken 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 Endpoints (Pfade) in der API
  • die für Anrufer 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-Website mit Grundstrukturen. 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: API_NAME.endpoints.YOUR_PROJECT_ID.cloud.goog
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 OpenAPI-Spezifikation. Dort finden Sie ein OpenAPI-Beispieldokument und eine Erläuterung der einzelnen Abschnitte der Datei.

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
servers:
  - url: https://API_NAME.endpoints.YOUR_PROJECT_ID.cloud.goog
    x-google-endpoint: {}
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 zeigt die Datei openapi.yaml aus dem Beispielcode der Anleitungen folgende Informationen:

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. Das Projekt flask-swagger könnte für Python-Nutzer und das Projekt swagger-node-express für Node-Entwickler interessant 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). Die vollständige Liste aller Tools und Integrationen finden Sie auf der Swagger-Website.

Weitere Informationen