更新时间:2022-02-21 GMT+08:00

限制与兼容性说明

在API网关中导入或者导出API时,限制与兼容性如下所示:

  • 只支持Swagger 2.0规范。
  • 请求参数类型定义和API网关规范存在差异,如下表所示。
    表1 请求参数类型和API网关参数类型差异

    Swagger类型

    API网关类型

    支持的参数属性字段

    integer

    long

    float

    double

    number

    maximum

    minimum

    default

    enum

    required

    description

    string

    string

    maxLength

    minLength

    default

    enum

    required

    description

    其它类型

    -

    -

  • API网关暂不支持formData和body位置的请求参数定义。
  • API网关中,header位置的参数名称,不区分大小写。
  • API网关暂不支持consumes和produces定义。
  • API网关导入和导出的Swagger对象和API网关对象定义的映射关系,如下表所示。

    Swagger对象

    API网关对象

    导入时行为

    导出时行为

    info.title

    API分组名称

    导入到新的分组:新的分组名称

    导入到已有分组:未使用

    支持汉字、英文、数字、下划线,且只能以英文或汉字开头,3 ~ 64字符

    填充为分组名称

    info.description

    API分组名称

    导入到新的分组:新的分组名称

    导入到已有分组:未使用

    填充为分组描述信息

    info.version

    API分组名称

    未使用

    用户指定

    未指定则使用当前时间

    host

    -

    未使用

    优先使用API分组的第一个自定义域名

    若分组未绑定自定义域名则使用分组的独立域名

    basePath

    -

    将与每条API的请求路径拼接起来使用

    未填充

    paths.path

    API请求路径

    与basePath拼接起来作为API请求路径

    填充为API请求路径

    operation.operationId

    API名称

    作为API名称

    填充为API名称

    operation.description

    API描述

    作为API描述

    填充为API描述

    operation.parameters

    API前端请求参数

    作为API请求参数

    填充为API请求参数

    operation.schemes

    API前端请求协议

    作为API请求协议

    填充为API请求协议

    operation.responses

    -

    未使用

    固定填充default响应定义

    operation.security

    API认证方式

    API认证方式

    结合x-apigateway-auth-type

    填充为API认证方式

    结合x-apigateway-auth-type

  • API请求路径模板语法差异,如下表所示。

    语法

    Swagger

    API网关

    /users/{userName}

    支持

    支持

    /users/prefix-{userName}

    /users/{userName}-suffix

    /users/prefix-{userName} -suffix

    支持

    前端请求定义不支持

    后端请求定义支持

    /users/{proxy+}

    不支持

    前端请求定义支持

    后端请求定义不支持

  • 导入API时支持的API网关扩展字段,如下所示。
    • x-apigateway-auth-type
    • x-apigateway-request-type
    • x-apigateway-match-mode
    • x-apigateway-cors
    • x-apigateway-any-method
    • x-apigateway-backend
      • x-apigateway-backend.parameters
      • x-apigateway-backend.httpEndpoints
      • x-apigateway-backend.httpVpcEndpoints
      • x-apigateway-backend.functionEndpoints
      • x-apigateway-backend.mockEndpoints
    • x-apigateway-backend-policies
      • x-apigateway-backend-policies.conditions
    • x-apigateway-ratelimit
    • x-apigateway-ratelimits
      • x-apigateway-ratelimits.policy
      • x-apigateway-ratelimits.policy.special
    • x-apigateway-access-control
    • x-apigateway-access-controls
      • x-apigateway-access-controls.policy
  • 后端策略限制,如下所示。
    • 默认后端类型为HTTP,策略后端支持HTTP、HTTP-VPC
    • 默认后端类型为HTTP-VPC,策略后端支持HTTP、HTTP-VPC
    • 默认后端类型为function,策略后端支持function
    • 默认后端类型为mock,策略后端支持mock