OpenAPI の概要

Google Cloud Endpoints は、OpenAPI 仕様のバージョン 2.0 を使用して記述された API をサポートしています。作成した API を実装するには、一般公開されている任意の REST フレームワーク(DjangoJersey など)を使用できます。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 仕様ともいう)が用意されており、ファイルの各セクションの簡単な説明があります。Cloud 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 の場合、JerseySpring の両方でアノテーションから OpenAPI ドキュメントを生成できるオープンソース プロジェクトがあります。また、Maven プラグインも用意されています。Python ユーザーには flask-swagger プロジェクト、Node デベロッパーには swagger-node-express が適しているでしょう。

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

次のステップ

このページは役立ちましたか?評価をお願いいたします。

フィードバックを送信...

OpenAPI を使用した Cloud Endpoints
ご不明な点がありましたら、Google のサポートページをご覧ください。