OpenAPI 機能の制限

現時点で 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: []

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."
}

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

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

既知の事象

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 では次のいずれかのスキームが必要です。

  • namekeyinquery です。
  • nameapi_keyinquery です。
  • namex-api-keyinheader です。

例:

"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 では構成タイプのドキュメントは生成されません。