OpenAPI 功能限制

目前,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: []
    

网址路径模板

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

例如,以下网址路径模板受支持:

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

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

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

针对网址根路径 / 的操作

Endpoints 接受包含针对根路径 / 的操作的 OpenAPI 文档。但是,根路径上的请求会被 ESP 拒绝。请注意,此限制仅适用于 ESP,ESPv2 Beta 版支持根路径 /

例如,以下 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 门户不呈现组合类型

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