OpenAPI の概要

Google Cloud Endpoints は、OpenAPI 仕様のバージョン 2.0 を使用して記述された API をサポートしています。 作成した API を実装するには、一般公開されている任意の REST フレームワーク（Django や Jersey など）を使用できます。API は、OpenAPI ドキュメントと呼ばれる JSON ファイルや YAML ファイルの中に記述されます。ここでは、OpenAPI を使用する利点について説明し、基本的な OpenAPI ドキュメントを示します。また、OpenAPI を使い始めるときに役立つ補足情報も提供します。

利点

OpenAPI を使用する主な利点としてドキュメントがあります。API を記述する OpenAPI ドキュメントがあると、API 用のリファレンス ドキュメントを容易に生成できます。詳細については、Cloud Endpoints Portal をご覧ください。

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

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

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

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

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

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

    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."

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

OpenAPI ドキュメントの生成

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

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

次のステップ