兼容性说明 支持OpenAPI规范。 OpenAPI规范（OAS），是定义一个标准的、与具体编程语言无关的RESTful API的规范。OpenAPI规范的前身是Swagger规范，API网关目前支持两种OpenAPI规范：Swagger 2.0或OpenAPI 3.0。为了方便区分，下文中OAS表示OpenAPI规范（包含Swagger 2.0或OpenAPI 3.0），Swagger表示Swagger 2.0规范，OpenAPI表示OpenAPI 3.0规范。 API网关导入或导出的OAS对象，与API网关对象定义的映射关系。 请求参数类型与API网关参数类型差异。 API请求路径模板语法差异。 导入API时支持的API网关扩展字段。 表1 OAS对象与API网关对象定义的映射关系 Swagger对象 OpenAPI对象 （以3.0.0为例） API网关对象 导入时行为 导出时行为 info.title info.title API分组名称 导入到新的分组：新的分组名称 导入到已有分组：未使用 支持汉字、英文、数字、下划线，且只能以英文或汉字开头，3 ~ 64字符 填充为分组名称 info.description info.description API分组描述 导入到新的分组：新的分组描述 导入到已有分组：未使用 填充为分组描述信息 info.version info.version 版本 未使用 用户指定 未指定则使用当前时间 host server.url API分组
域名 未使用 优先使用API分组的第一个自定义域名 如果分组未绑定自定义域名则使用分组的独立域名 basePath - - 将与每条API的请求路径拼接起来使用 未填充 paths.path paths.path API请求路径 与basePath拼接起来作为API请求路径 填充为API请求路径 operation.operationId operation.operationId API名称 作为API名称 填充为API名称 operation.description operation.description API描述 作为API描述 填充为API描述 operation.parameters operation.parameters API前端请求参数 作为API请求参数 填充为API请求参数 operation.schemes - API前端请求协议 作为API请求协议 填充为API请求协议 operation.responses operation.responses - 未使用 固定填充default响应定义 operation.security operation.security API认证方式 API认证方式 结合x-apigateway-auth-type 填充为API认证方式 结合x-apigateway-auth-type 表2 请求参数类型和API网关参数类型差异 OAS类型Swagger类型 API网关类型 支持的参数属性字段 integer long float double number maximum minimum default enum required description string string maxLength minLength default enum required description 其它类型 不支持 不支持 表3 API请求路径模板语法差异 语法 OAS类型Swagger类型 API网关 /users/{userName} 支持 支持 /users/prefix-{userName} /users/{userName}-suffix /users/prefix-{userName} -suffix 支持 前端请求定义不支持 后端请求定义支持 /users/{proxy+} 不支持 前端请求定义支持 后端请求定义不支持
