此页面由 Cloud Translation API 翻译。

OpenAPI 功能限制

OpenAPI | gRPC

目前，Cloud Endpoints 只接受 OpenAPI 规范第 2 版。

以下部分介绍了 Endpoints 上 OpenAPI 功能的限制。

范围被忽略

虽然 Endpoints 接受已在安全方案对象内定义了范围的 OpenAPI 文档，但向您的 API 发送请求时，Extensible Service Proxy (ESP) 和 Cloud Endpoints Frameworks 都不会检查已定义的范围。

多个安全性要求

您可以在 OpenAPI 文档中指定多个安全性要求。本部分介绍 ESP 支持的安全方案。

包含 API 密钥的安全性要求

当其中一个安全方案是 API 密钥时，ESP 不支持替代（逻辑 OR）安全性要求。例如，ESP 不支持以下安全性要求列表：

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

此定义要求某项操作接受符合 petstore_auth 要求或 api_key 要求的请求。

但请注意，ESP 支持安全性要求合取（逻辑 AND），因此您可以同时要求 API 密钥和 OAuth2 身份验证。例如，以下安全性要求列表受支持：

security:
- petstore_auth: []
  api_key: []

此定义要求某项操作接受同时符合 petstore_auth 要求和 api_key 要求的请求。

OAuth2 的安全性要求

ESP 支持安全性替代（逻辑 OR）安全性要求，但仅限于 OAuth2 身份验证安全方案。例如，以下安全性要求列表受支持：

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

安全定义验证

ESP 不会验证所有安全要求（在 API 级别或方法级别显示），也会出现在 securityDefinitions 部分。因此，如果 API 规范使用例如未定义的安全架构，那么未经身份验证的请求可能会通过 API、未定义安全密钥的级别。请确保所有 API 及其方法使用的安全密钥在“security” OpenAPI 文档中的定义

网址路径模板

Endpoints 仅支持与整个路径段（由斜杠 / 分隔）对应的网址路径模板参数。不支持与部分路径细分对应的网址路径模板参数。

例如，以下网址路径模板受支持：

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

以下网址路径模板不受支持，会被拒绝：

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

针对网址根路径 `/` 的操作

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

上传文件

端点不接受上传文件的 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 别名限制

端点在一个集群中最多可以支持 200 个 YAML 别名节点 OpenAPI 文档。如果一个 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 密钥安全性定义会在传入请求中被忽略。

Cloud Endpoints 门户不呈现组合类型

尽管 Endpoints 接受具有组合类型的 OpenAPI 文档，即定义中包含 allOf 的类型，但 Endpoints 门户不会为组合类型生成文档。