OpenAPI 3.x 功能限制

本文說明將 OpenAPI 3.x 搭配 Endpoints 使用時的功能限制。

如要進一步瞭解支援的 OpenAPI 規範版本，請參閱 OpenAPI 總覽。

OpenAPI 3.x 的新限制

本節說明支援 OpenAPI 3.x 後的新限制。

伺服器

OpenAPI 3.x 支援多個 server 物件，可定義主機和基本路徑。不過，Cloud Endpoints 只會使用單一伺服器物件來設定主機名稱和基本路徑，並以 x-google-endpoint 擴充功能識別。

雖然您可以在 OpenAPI 規格中定義多個伺服器，但 Cloud Endpoints 只會使用具有 x-google-endpoint 擴充功能的伺服器。您只能在一個伺服器上定義 x-google-endpoint 擴充功能。

Cloud Endpoints 需要主機名稱，因此只有一個伺服器必須有 x-google-endpoint 擴充功能。

舉例來說，下列伺服器定義對 Cloud Endpoints 而言是有效的：

servers:
  - url: https://my-api.endpoints.my-project-id.cloud.goog
    x-google-endpoint: {}

servers:
  - url: https://my-api.endpoints.my-project-id.cloud.goog
    x-google-endpoint: {}
  - url: https://example.com

以下伺服器定義對 Endpoints 而言無效：

servers:
  - url: https://my-api-1.endpoints.my-project-id.cloud.goog
    x-google-endpoint: {}
  - url: https://my-api-2.endpoints.my-project-id.cloud.goog
    x-google-endpoint: {}

下列定義也不適用於 Cloud Endpoints：

servers:
  - url: https://my-api.endpoints.my-project-id.cloud.goog

多個檔案中的伺服器

如果上傳多個 OpenAPI 檔案，所有檔案都必須遵守servers區段限制。如果其中一個檔案包含副檔名為 x-google-endpoint 的伺服器，則所有檔案都必須定義副檔名為 x-google-endpoint 的伺服器。

此外，所有含有 x-google-endpoint 副檔名的伺服器都必須在伺服器網址中使用相同的主機，且所有檔案的 x-google-endpoint 設定必須相同。伺服器網址中的 basepath 可能不同。

相對網址

Cloud Endpoints 需要主機名稱，因此不支援相對網址。

不支援的擴充功能

OpenAPI 3.x 不支援 x-google-allow 擴充功能。

現有限制

本節說明 OpenAPI 2.0 的限制，這些限制也適用於 OpenAPI 3.x。

忽略的範圍

雖然您可以在安全性配置物件中定義範圍，但 ESP 或 Cloud Endpoints Frameworks 不會檢查這些範圍。

多項安全性要求

您可以在 OpenAPI 文件中指定多項安全要求。

  • 含有 API 金鑰的安全性要求：當安全性配置中有一項是 API 金鑰時，Cloud Endpoints 不支援其他的 (邏輯 OR) 安全性要求。Cloud Endpoints 支援組合 (邏輯 AND)，因此您可以要求同時使用 API 金鑰和 OAuth2 驗證。

  • OAuth2 的安全性要求：Cloud Endpoints 支援不同 OAuth2 驗證配置的其他安全性要求 (邏輯 OR)。除非額外的安全性要求是 API 金鑰，否則 Cloud Endpoints 不支援連詞 (邏輯 AND)。

  • 選用安全性要求：OpenAPI 3 支援選用安全性，方法是加入空白要求 ({})。API 金鑰支援這項功能，但 OAuth 不支援。

驗證安全性定義

如果是 OpenAPI 3.x，使用未定義的安全機制會導致錯誤，且 Cloud Endpoints 會拒絕規格。這與 OpenAPI 2.0 不同，後者只會產生警告。

網址路徑範本

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

舉例來說，Cloud Endpoints 支援 /items/{itemId}，但不支援 /items/overview.{format}。

網址根路徑 / 的作業

雖然 OpenAPI 文件接受根路徑 / 的作業，但可擴充服務 Proxy 會拒絕根路徑的要求。這項限制不適用於支援根路徑的 ESPv2。

參數、結構定義、要求主體和類型

可擴充服務 Proxy 和 ESP 會忽略大部分的參數、結構定義、要求主體和類型定義。可擴充服務 Proxy 和 ESP 不會強制執行必要參數和類型定義，而是將要求轉送至 API。

可擴充服務 Proxy 和 ESP 只支援要求參數中的基本類型。

外部類型參考資料

Cloud Endpoints 不支援 OpenAPI 文件以外類型的參考資料。舉例來說，您無法使用 $ref 連結至外部網址。

服務主機位址中的自訂通訊埠

您無法在 servers 物件的 url 中使用自訂連接埠。

YAML 別名限制

OpenAPI 文件最多可包含 200 個 YAML 別名節點。

非重複要求主體

每個作業只能定義一個 requestBody，且必須為非重複類型。