OpenAPI 3.x の機能の制限事項

このドキュメントでは、Endpoints で OpenAPI 3.x を使用する場合の機能の制限について説明します。

サポートされている OpenAPI 仕様バージョンの詳細については、OpenAPI の概要をご覧ください。

OpenAPI 3.x の新しい制限事項

このセクションでは、OpenAPI 3.x のサポートで新しく追加された OpenAPI の制限について説明します。

サーバー

OpenAPI 3.x では、複数の server オブジェクトを使用してホストとベースパスを定義できます。ただし、Cloud Endpoints では、x-google-endpoint 拡張機能で識別される単一のサーバー オブジェクトを使用して、ホスト名とベースパスを構成します。

OpenAPI 仕様で複数のサーバーを定義できますが、Cloud Endpoints では x-google-endpoint 拡張機能を持つサーバーのみが使用されます。x-google-endpoint 拡張機能は 1 つのサーバーでのみ定義できます。

Cloud Endpoints の場合、ホスト名が必要なため、x-google-endpoint 拡張機能を持つサーバーは 1 つのみにする必要があります。

たとえば、次のサーバー定義は Cloud Endpoints で有効 です。

servers:
  - url: https://my-api.endpoints.my-project-id.cloud.goog
    x-google-endpoint: {}

servers:
  - url: https://my-api.endpoints.my-project-id.cloud.goog
    x-google-endpoint: {}
  - url: https://example.com

次のサーバー定義は Endpoints で無効 です。

servers:
  - url: https://my-api-1.endpoints.my-project-id.cloud.goog
    x-google-endpoint: {}
  - url: https://my-api-2.endpoints.my-project-id.cloud.goog
    x-google-endpoint: {}

次の定義も Cloud Endpoints では無効 です。

servers:
  - url: https://my-api.endpoints.my-project-id.cloud.goog

複数のファイルにまたがるサーバー

複数の OpenAPI ファイルをアップロードする場合、すべてのファイルが servers セクションの制限に従う必要があります。1 つのファイルに x-google-endpoint 拡張機能を持つサーバーが含まれている場合は、すべてのファイルで x-google-endpoint 拡張機能を持つサーバーを定義する必要があります。

さらに、x-google-endpoint 拡張機能を持つすべてのサーバーは、サーバー URL で同一のホストを使用する必要があり、x-google-endpoint 構成はすべてのファイルで同一である必要があります。サーバー URL のベースパスは異なる場合があります。

相対 URL

Cloud Endpoints にはホスト名が必要なため、相対 URL はサポートされていません。

サポートされていない拡張機能

OpenAPI 3.x では、x-google-allow 拡張機能はサポートされていません。

既存の制限事項

このセクションでは、OpenAPI 2.0 に存在し、OpenAPI 3.x にも適用される制限について説明します。

スコープが無視される

セキュリティ スキーム オブジェクトでスコープを定義できますが、ESP または Cloud Endpoints Frameworks ではチェックされません。

複数のセキュリティ要件

OpenAPI ドキュメントに複数のセキュリティ要件を指定できます。

  • API キーを使用したセキュリティ要件: スキームの 1 つが API キーの場合、Cloud Endpoints は択一的（論理 OR）セキュリティ要件をサポートしません。Cloud Endpoints は連結（論理 AND）をサポートしているため、API キーと OAuth2 認証の両方を必須にできます。

  • OAuth2 のセキュリティ要件: Cloud Endpoints は、さまざまな OAuth2 認証スキームの択一的（論理 OR）セキュリティ要件をサポートしています。追加のセキュリティ要件が API キーでない限り、Cloud Endpoints は連結（論理 AND）をサポートしません。

  • 省略可能なセキュリティ要件: OpenAPI 3 は、空の要件（{}）を含めることで、省略可能なセキュリティをサポートします。API キーはこれをサポートしますが、OAuth はサポートしません。

セキュリティ定義の検証

OpenAPI 3.x では、未定義のセキュリティ スキーマを使用するとエラーが発生し、Cloud Endpoints は仕様を拒否します。これは OpenAPI 2.0 からの変更です。OpenAPI 2.0 では、この場合でも警告のみが生成されます。

URL パス テンプレート

Cloud Endpoints は、パスセグメント全体（/ で区切られた部分）に対応する URL パス テンプレート パラメータのみをサポートします。Cloud Endpoints は、パスセグメントの一部に対応するパラメータをサポートしていません。

たとえば、Cloud Endpoints は /items/{itemId} をサポートしますが、/items/overview.{format} はサポートしません。

URL ルートパス / 上のオペレーション

OpenAPI ドキュメントはルートパス / 上のオペレーションを受け入れますが、Extensible Service Proxy はルートパスへのリクエストを拒否します。この制限は、ルートパスをサポートする ESPv2 には適用されません。

パラメータ、スキーマ、リクエスト本文、型

Extensible Service Proxy と ESP は、ほとんどのパラメータ、スキーマ、リクエスト本文、型の定義を無視します。Extensible Service Proxy と ESP は、必須パラメータと型の定義を適用せず、リクエストを API に転送します。

Extensible Service Proxy と ESP は、リクエスト パラメータでプリミティブ型のみをサポートします。

外部型参照

Cloud Endpoints は、OpenAPI ドキュメントの外部にある型への参照をサポートしていません。たとえば、外部 URL に $ref を使用することはできません。

サービスホスト アドレスのカスタムポート

servers オブジェクトの url でカスタムポートを使用することはできません。

YAML エイリアスの制限

OpenAPI ドキュメントには、最大 200 個の YAML エイリアスノードを含めることができます。

繰り返しのないリクエスト本文

オペレーションごとに定義できる requestBody は 1 つのみで、繰り返しのない型にする必要があります。