OpenAPI 機能の制限

OpenAPI   |  gRPC

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

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

スコープが無視される

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

複数のセキュリティ要件

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

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

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

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

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

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

security:
- petstore_auth: []
  api_key: []

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

OAuth2 のセキュリティ要件

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

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

セキュリティ定義の検証

ESP はすべてのセキュリティ要件（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 は、ほとんどのパラメータと型の定義を無視します。

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

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

  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 キーのセキュリティ定義は無視されます。

Cloud Endpoints Portal では構成タイプがレンダリングされない

Endpoints は構成タイプ（定義に allOf が含まれるタイプ）の OpenAPI ドキュメントを受け取りますが、Endpoints Portal では構成タイプのドキュメントは生成されません。