OpenAPI 機能の制限

OpenAPI   |  gRPC

Cloud Endpoints が対応しているのは OpenAPI 仕様のバージョン 2 のみです。

以下のセクションでは、Endpoints での OpenAPI 機能の制限について説明します。

スコープが無視される

Endpoints は、セキュリティ スキーム オブジェクトでスコープが定義された OpenAPI ドキュメントを受け入れますが、リクエストが API に送信されたとき、Extensible Service Proxy（ESP）、Extensible Service Proxy V2（ESPv2）、Cloud Endpoints Frameworks のいずれも、定義されたスコープをチェックしません。

複数のセキュリティ要件

OpenAPI ドキュメントに複数のセキュリティ要件を指定できます。 このセクションでは、ESP と ESPv2 がサポートするセキュリティ スキームについて説明します。

API キーを含むセキュリティ要件

セキュリティ スキームの 1 つが API キーである場合、ESP と ESPv2 は代替（論理 OR）セキュリティ要件をサポートしません。たとえば、ESP と ESPv2 では次のセキュリティ要件リストはサポートされません。

security:
- petstore_auth: []
- api_key: []

この定義では、petstore_auth 要件または api_key 要件のいずれかに準拠するリクエストを受け入れるオペレーションが必要です。

ただし、ESP と ESPv2 はセキュリティ要件の連結（論理 AND）をサポートしているため、API キーと OAuth2 認証の両方を必須にできます。たとえば、次のセキュリティ要件リストはサポートされます。

security:
- petstore_auth: []
  api_key: []

この定義では、同時に petstore_auth 要件と api_key 要件の両方に準拠するリクエストを受け入れるオペレーションが必要です。

OAuth2 のセキュリティ要件

ESP と ESPv2 は、OAuth2 認証セキュリティ スキームでのみ、セキュリティの代替（論理 OR）セキュリティ要件をサポートします。たとえば、次のセキュリティ要件リストはサポートされます。

security:
  - firebase1: []
  - firebase2: []

セキュリティ定義の検証

ESP と ESPv2 は、すべてのセキュリティ要件（API レベルまたはメソッドレベル）が securityDefinitions セクションに存在することを検証しません。そのため、API 仕様で未定義のセキュリティ スキーマが使用されている場合、未定義のリクエストは、未定義のセキュリティキーが設定されているレベルで API に到達する可能性があります。API とそのメソッドで使用されるすべてのセキュリティ キーが、OpenAPI ドキュメントのセキュリティ定義で定義されていることを確認します。

URL パス テンプレート

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

たとえば、次の URL パス テンプレートはサポートされます。

• /items/{itemId}
• /items/{itemId}/subitems

次の URL パス テンプレートはサポートされず、拒否されます。

• /items/overview.{format}
• /items/prefix_{id}_suffix

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

Endpoints は、ルートパス「/」上のオペレーションを含む OpenAPI ドキュメントを受け入れます。ただし、ルートパス上のリクエストは ESP によって拒否されます。この制限は ESP のみを対象とするものであり、ESPv2 はルートパス / をサポートしています。

たとえば、次の OpenAPI ドキュメント スニペットは受け入れられます。

paths:
  /:
    post:
      operationId: "root"
      responses:
        200:
          description: "Success"
          schema:
            type: string

ただし、POST / に対する後続のリクエストは拒否され、次のエラーが発生します。

{
   "code": 5,
   "details": [
       {
           "@type": "type.googleapis.com/google.rpc.DebugInfo",
           "detail": "service_control",
           "stackEntries": []
       }
   ],
   "message": "Method does not exist."
}

ファイルのアップロード

Endpoints は、ファイル アップロード パラメータに type: file を受け入れません。代わりに type: string を使用する必要があります。

たとえば、次の type: file スニペットは許可されません。

paths:
  /upload:
    post:
      summary: Uploads a file.
      consumes:
        - multipart/form-data
      parameters:
        - in: formData
          name: upfile
          type: file
          description: The file to upload.

一方、次の type: string は使用できます。

paths:
  /upload:
    post:
      summary: Uploads a file.
      consumes:
        - multipart/form-data
      parameters:
        - in: formData
          name: upfile
          type: string
          description: The file to upload.

パラメータ、スキーマ、型

ESP と ESPv2 は、ほとんどのパラメータと型の定義を無視します。

Endpoints は必要なパラメータと型の定義が含まれた OpenAPI ドキュメントを受け取りますが、ESP と ESPv2 はこれらの定義を適用することなく、受信リクエストを API に転送します。以下に、ESP と ESPv2 で適用されない定義の例を一部示します。

• フォームデータ パラメータ:

  parameters:
  - name: avatar
    in: formData
    description: "The avatar of the user"
    type: string

• 必須パラメータ:

  parameters:
  - name: message
    in: query
    description: "Message to send"
    required: true
    type: string

• 配列コレクション形式:

  parameters:
  - name: items
    in: query
    description: "List of item IDs"
    required: true
    type: array
    items:
      type: string
    collectionFormat: tsv

• 型の構成:

  definitions:
    base:
      properties:
        message:
          type: string
    extended:
      description: "Extends the base type"
      allOf:
      - $ref: "#/definitions/base"
      - type: object
        properties:
          extension:
            type: string

• ステータス コード毎の各種レスポンス:

  responses:
    200:
      description: "Echo"
      schema:
        $ref: "#/definitions/EchoResponse"
    400:
      description: "Error"
      schema:
        type: string

外部型参照

Endpoints は、OpenAPI ドキュメントの外部にある型への参照をサポートしていません。たとえば、Endpoints では以下を含む OpenAPI ドキュメントが拒否されます。

parameters:
- name: user
  description: User details
  in: body
  schema:
    $ref: "https://example.com/mytype.json"

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

Endpoints では、OpenAPI ドキュメントの host フィールドにカスタムポートを使用できません。たとえば、Endpoints では次のような OpenAPI ドキュメントが拒否されます。

swagger: 2.0
host: example.com:8080
schemes:
- http

YAML エイリアスの制限事項

Endpoints は、OpenAPI ドキュメントで最大 200 個の YAML エイリアス ノードをサポートできます。OpenAPI ドキュメントに 200 を超える YAML エイリアスがある場合は、この上限を遵守するために、可能な限りエイリアスの参照解除を行うことをおすすめします。

既知の事象

OpenAPI ドキュメントが拒否される

gcloud endpoints services deploy を使用して OpenAPI ドキュメントをデプロイすると、Endpoints では次の対象を含む OpenAPI ドキュメントが拒否されます。

• 以下のような配列の本体パラメータ:

  parameters:
  - name: message
    description: "Message to echo"
    in: body
    schema:
      type: array
      items:
        type: string

• 以下の例のように、末尾にスラッシュが付いているパス:

  paths:
    "/echo/":
      post:
        description: "Echo back a given message."
  

  この問題を解決するには、/echo/ から末尾のスラッシュを削除します。

  paths:
    "/echo":
      post:
        description: "Echo back a given message."
  

API キーの定義の制限事項

OpenAPI ドキュメントのセキュリティ定義オブジェクトで API キーを指定する場合、Endpoints では次のいずれかのスキームが必要です。

• name は key、in は query です。
• name は api_key、in は query です。
• name は x-api-key、in は header です。

例:

"securityDefinitions": {
  "api_key_0": {
        "type": "apiKey",
        "name": "key",
        "in": "query"
    },
  "api_key_1": {
        "type": "apiKey",
        "name": "api_key",
        "in": "query"
    }
  "api_key_2": {
        "type": "apiKey",
        "name": "x-api-key",
        "in": "header"
    },
}

他の種類の API キーのセキュリティ定義を使用して OpenAPI ドキュメントをデプロイした場合、Endpoints がそれらを受け入れる場合でも警告が出されることがあります。 ただし、受信リクエストでは API キーのセキュリティ定義は無視されます。