OpenAPI

Cloud Endpoints unterstützt APIs, die mit Version 2.0 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.

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.

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

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 OpenAPI-Dokument aus der Cloud Endpoints-Kurzanleitung veranschaulicht diese Grundstruktur:

    swagger: "2.0"
    info:
      title: "Airport Codes"
      description: "Get the name of an airport from its three-letter IATA code."
      version: "1.0.0"
    # This field will be replaced by the deploy_api.sh script.
    host: "YOUR-PROJECT-ID.appspot.com"
    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 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