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 ファイルは、次の点も示しています。
- API キーを使用するためのパスの構成方法
- 認証用のさまざまなセキュリティ スキーム
- Cloud Endpoints API で利用可能な OpenAPI の拡張
OpenAPI ドキュメントの生成
ご使用の言語によっては、OpenAPI ドキュメントを生成できる場合があります。Java の場合、Jersey と Spring の両方でアノテーションから OpenAPI ドキュメントを生成できるオープンソース プロジェクトがあります。また、Maven プラグインも用意されています。Python ユーザーには flask-swagger プロジェクト、Node デベロッパーには swagger-node-express が適しているでしょう。
OpenAPI コミュニティは、OpenAPI ドキュメントの生成（一部の言語では自動生成）に役立つツールを継続的に開発しています。ツールと統合の詳細なリストについては、Swagger ウェブサイトをご覧ください。