Open API 仕様

Open API 仕様(旧名 Swagger 仕様)は REST API を定義するための業界標準です。その管理を行う目的で Open API Initiative が近年組織されたとき、Google はその創設メンバーの 1 社として参加しました。デベロッパーにとって、より良いツールチェーンをサポートするためには仕様をオープンにすることが重要だと Google は考えています。

利点

Endpoints のような API 管理ツールとの統合とは別に、Open API 仕様の採用を決めたのにはさまざまな理由があります。主な理由は、文書化のためです。API 向けの Open API 仕様を使用している場合、双方向型の文書化ツールとしてプロジェクトに Swagger UI を容易に追加できます。簡易的な手順については Adding Swagger UI to your project をご覧ください。

Open API 仕様を使用する利点としては、クライアント ライブラリをさまざまな言語で作成したり、サーバースタブを作成したりできるほか、ユーザーの適合性の検証するため、およびサンプルを生成するために利用できるプロジェクトが用意されていることなどが挙げられます。

Open API 仕様を生成する

使用している言語に応じて、仕様を生成できる場合があります。Java では、アノテーションから仕様を生成できる Jersey と、Spring の両方に対してオープンソース プロジェクトがあります。Maven plugin も用意しています。 flask-swagger は Python ユーザーのための、swagger-node-express は Node デベロッパーのためのプロジェクトです。統合の完全なリストについては Swagger サイトをご覧ください。

サポートされていない Open API 仕様の機能

現時点では、Open API の仕様 v2.0 の JSON ファイルと YAML ファイルのみ対応しています。

以下の Open API 仕様の機能はまだ Google Cloud Endpoints でサポートしていません。

  • 多層性(基本型と派生型)
  • オペレーション ボディ パラメータのファイル型({“type”:“file”}
  • ヘッダーのパラメータ
  • フォーム データ パラメータ
  • オプション オペレーション
  • ヘッド オペレーション
  • ステータス コード毎の各種レスポンス
  • 型に関する、仕様書以外の情報源("$ref": "http://mydomain/mytype.json"
  • JSON: 型: null
  • allof を使用する型の構成
  • collectionFormat
  • 依存関係
  • セキュリティ ポリシーと複雑なロジックを組み合わせる(例として AND と OR など)には(petstore_advance_auth)または(petstore_auth AND api_key)を必要とします。
  • ランタイムの制約(allowEmptyValue、readonly、required、enums)
このページは役立ちましたか?評価をお願いいたします。

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

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