OpenAPI 功能限制

OpenAPI   |  gRPC

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

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

范围被忽略

虽然 Endpoints 接受已在安全方案对象内定义了范围的 OpenAPI 文档，但向您的 API 发送请求时，Extensible Service Proxy (ESP)、Extensible Service 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 文档。但是，根路径上的请求会被 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 密钥安全性定义会在传入请求中被忽略。