OpenAPI 功能限制

Cloud Endpoints 目前僅接受第 2 版的 OpenAPI 規範。

以下各節說明 Endpoints 上的 OpenAPI 功能相關限制。

忽略的範圍

雖然 Endpoints 會接受在安全性配置物件中定義範圍的 OpenAPI 說明文件，但是系統將要求傳送到您的 API 時，可擴充服務 Proxy (ESP)、可擴充服務 Proxy V2 (ESPv2) 或 Cloud Endpoints Frameworks 都不會檢查定義的範圍。

多項安全性要求

您可以在 OpenAPI 文件中指定多項安全要求。本節將說明 ESP 和 ESPv2 支援的安全性配置。

含有 API 金鑰的安全性要求

當安全性配置中有一項是 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 支援其他的安全性要求 (邏輯 OR)，但僅限於 OAuth2 的驗證安全性配置。支援的安全性要求清單範例如下：

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

安全性定義驗證

ESP 和 ESPv2 不會驗證所有安全性要求 (無論是 API 層級或方法層級) 是否也出現在 securityDefinitions 區段中。因此，如果 API 規格使用未定義的安全性結構定義，未經驗證的要求可能會透過 API 傳送，且會在未定義的安全性金鑰設定層級傳送。請確認 API 和其方法使用的所有安全性金鑰，皆已在 OpenAPI 文件的安全性定義下定義。

網址路徑範本

Endpoints 僅支援對應至整個路徑區段 (以斜線 / 分隔) 的網址路徑範本參數，而不支援只對應部分路徑區段的網址路徑範本參數。

系統支援的網址路徑範本實例如下：

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

系統不支援下列網址路徑範本，因此這類範本會遭到拒絕：

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

網址根路徑 / 的作業

Endpoints 接受包含根路徑 / 作業的 OpenAPI 文件，不過根路徑上的要求會遭到可擴充服務 Proxy (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."
}

上傳檔案

端點不接受 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 文件中的 YAML 別名超過 200 個，建議您盡可能取消別名的參照，以符合此限制。

已知錯誤

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 金鑰安全性定義會遭到系統忽略。