OpenAPI の概要

Google Cloud Endpoints は、OpenAPI 仕様のサポートされているバージョンを使用して記述された API をサポートしています。

作成した API を実装するには、一般公開されている任意の REST フレームワーク（Django や Jersey など）を使用できます。

API は、OpenAPI ドキュメントと呼ばれる JSON ファイルや YAML ファイルの中に記述されます。ここでは、OpenAPI を使用する利点について説明し、基本的な OpenAPI ドキュメントを示します。また、OpenAPI を使い始めるときに役立つ補足情報も提供します。

サポートされている OpenAPI のバージョン

Cloud Endpoints は、次の OpenAPI バージョンをサポートしています。

  1. OpenAPI 2.0（旧 Swagger）
  2. OpenAPI 3.0.x

各バージョンの公式仕様は、OpenAPI イニシアチブから入手できます。

パッチ バージョンのサポート

OpenAPI 仕様では、パッチ バージョン（3.0.1、3.0.2）は修正または明確化のみを導入し、新機能は追加しません。そのため、Cloud Endpoints は 3.0 のすべてのパッチ バージョンをサポートしています。

用語

Cloud Endpoints のドキュメント全体で、OpenAPI 3.x は、サポートされているすべての OpenAPI 3 バージョンを指します。

利点

OpenAPI を使用する主な利点としてドキュメントがあります。API を記述する OpenAPI ドキュメントがあると、API 用のリファレンス ドキュメントを生成できます。

OpenAPI を使用するその他の利点は以下のとおりです。

  • クライアント ライブラリを多数の言語で生成します。
  • サーバースタブを生成します。
  • プロジェクトを使用して適合性の検証や、サンプルの生成ができます。

OpenAPI ドキュメントの基本構造

OpenAPI ドキュメントは REST API のサーフェスを記述し、次のような情報を定義します。

  • API の名前と説明。
  • API 内の個々のエンドポイント（パス）。
  • 呼び出し元の認証方法。

OpenAPI ドキュメントの構造は、使用する OpenAPI のバージョンによって異なります。次の例では、OpenAPI 2.0 と OpenAPI 3.x の構造について説明します。

OpenAPI 2.0

OpenAPI を初めて使用する場合は、Swagger 基本構造のウェブサイトをご覧ください。このサイトにはサンプル OpenAPI ドキュメント（Swagger 仕様ともいう）が用意されており、ファイルの各セクションの簡単な説明があります。次の例は、この基本構造を示しています。

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

OpenAPI を初めて使用する場合は、OpenAPI 仕様をご覧ください。このサイトにはサンプル OpenAPI ドキュメントが用意されており、ファイルの各セクションの説明があります。

次の例は、この基本構造を示しています。

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

この基本構造に加えて、チュートリアルで使われているサンプルコードの openapi.yaml ファイルは、次の点も示しています。

OpenAPI ドキュメントの生成

ご使用の言語によっては、OpenAPI ドキュメントを生成できる場合があります。Java の場合、Jersey と Spring の両方でアノテーションから OpenAPI ドキュメントを生成できるオープンソース プロジェクトがあります。また、Maven プラグインも用意されています。Python ユーザーには flask-swagger プロジェクト、Node デベロッパーには swagger-node-express が適しているでしょう。

OpenAPI コミュニティは、OpenAPI ドキュメントの生成（一部の言語では自動生成）に役立つツールを継続的に開発しています。ツールと統合の詳細なリストについては、Swagger ウェブサイトをご覧ください。

次のステップ