# 导入导出API的兼容性说明 在API网关中导入或导出API时，OpenAPI规范（OpenAPI Specification，简称OAS）与API网关对象定义之间存在兼容性差异，主要体现在对象映射、参数类型、路径语法等方面。详细兼容性说明请参见下文。 - API网关支持OpenAPI规范。 OpenAPI规范是定义一个标准的、与具体编程语言无关的RESTful API的规范。OpenAPI规范的前身是Swagger规范，API网关目前支持两种OpenAPI规范：Swagger 2.0或OpenAPI 3.0。**为了方便区分，下文中OAS规范包含Swagger 2.0或OpenAPI 3.0，Swagger表示Swagger 2.0规范，OpenAPI表示OpenAPI 3.0规范** **。** - API网关支持导入或导出OAS规范的API，同时也支持在导入OAS规范的API中添加网关的[扩展字段](https://support.huaweicloud.com/usermanual-apig/apig_03_0084.html)。 - OAS对象与API网关对象定义通过映射规则实现数据转换和同步，这两种对象定义的映射规则请参考[表1]。 - OAS请求参数类型与API网关参数类型拥有不同的规范体系，因此两者存在差异，详情请参考[表2]。 - OAS与API网关的API请求路径存在语法差异，详情请参考[表3]。 表1OAS对象与API网关对象定义的映射关系 | Swagger对象 | OpenAPI对象 （以3.0.0为例） | API网关对象 | 导入时行为 | 导出时行为 | |:---|:---|:---|:---|:---| | [info.title](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#info-object) | [info.title](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.0.md#info-object) | API分组名称 | 导入到新的分组：新的分组名称 导入到已有分组：未使用 支持中文、英文、数字、下划线，且只能以英文或中文开头，3 \~ 64字符 | 填充为分组名称 | | [info.description](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#info-object) | [info.description](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.0.md#info-object) | API分组描述 | 导入到新的分组：新的分组描述 导入到已有分组：未使用 | 填充为分组描述信息 | | [info.version](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#info-object) | [info.version](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.0.md#info-object) | 版本 | 未使用 | 用户指定 未指定则使用当前时间 | | [host](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#swagger-object) | [server.url](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.0.md#server-object) | API分组域名 | 未使用 | 优先使用API分组的第一个自定义域名 如果分组未绑定自定义域名则使用分组的独立域名 | | [basePath](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#swagger-object) | - | - | 将与每条API的请求路径拼接起来使用 | 未填充 | | [paths.path](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#paths-object) | [paths.path](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.0.md#paths-object) | API请求路径 | 与basePath拼接起来作为API请求路径 | 填充为API请求路径 | | [operation.operationId](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#operation-object) | [operation.operationId](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.0.md#operation-Object) | API名称 | 作为API名称 | 填充为API名称 | | [operation.description](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#operation-object) | [operation.description](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.0.md#operation-Object) | API描述 | 作为API描述 | 填充为API描述 | | [operation.parameters](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#operation-object) | [operation.parameters](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.0.md#operation-Object) | API前端请求参数 | 作为API请求参数 | 填充为API请求参数 | | [operation.schemes](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#operation-object) | - | API前端请求协议 | 作为API请求协议 | 填充为API请求协议 | | [operation.responses](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#operation-object) | [operation.responses](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.0.md#operation-Object) | - | 未使用 | 固定填充default响应定义 | | [operation.security](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#operation-object) | [operation.security](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.0.md#operation-Object) | API认证方式 | API认证方式 结合[x-apigateway-auth-type](https://support.huaweicloud.com/usermanual-apig/apig_03_0085.html) | 填充为API认证方式 结合[x-apigateway-auth-type](https://support.huaweicloud.com/usermanual-apig/apig_03_0085.html) | 表2OAS请求参数类型和API网关参数类型差异 | OAS类型 | API网关类型 | 支持的参数属性字段 | |:---|:---|:---| | integer long float double | number | maximum minimum default enum required description | | string | string | maxLength minLength default enum required description | | 其它类型 | 不支持 | 不支持 | 表3API请求路径模板语法差异 | 语法 | OAS | API网关 | |:---|:---|:---| | /users/{userName} | 支持 | 支持 | | /users/prefix-{userName} /users/{userName}-suffix /users/prefix-{userName}-suffix | 支持 | 前端请求定义不支持 后端请求定义支持 | | /users/{proxy+} | 不支持 | 前端请求定义支持 后端请求定义不支持 |