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 では次のように指定する必要があります。

  • name フィールドは key にする必要があります。
  • in フィールドは query にする必要があります。

例:

"securityDefinitions": {
      "api_key": {
        "type": "apiKey",
        "name": "key",
        "in": "query"
      }
    

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

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

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