更新时间：2026-06-30 GMT+08:00
导入导出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中添加网关的扩展字段。
- OAS对象与API网关对象定义通过映射规则实现数据转换和同步，这两种对象定义的映射规则请参考表1。
- OAS请求参数类型与API网关参数类型拥有不同的规范体系，因此两者存在差异，详情请参考表2。
- OAS与API网关的API请求路径存在语法差异，详情请参考表3。
| Swagger对象 | OpenAPI对象 （以3.0.0为例） | API网关对象 | 导入时行为 | 导出时行为 |
|---|---|---|---|---|
| API分组名称 | 导入到新的分组：新的分组名称 导入到已有分组：未使用 支持汉字、英文、数字、下划线，且只能以英文或汉字开头，3 ~ 64字符 | 填充为分组名称 | ||
| API分组描述 | 导入到新的分组：新的分组描述 导入到已有分组：未使用 | 填充为分组描述信息 | ||
| 版本 | 未使用 | 用户指定 未指定则使用当前时间 | ||
| API分组域名 | 未使用 | 优先使用API分组的第一个自定义域名 如果分组未绑定自定义域名则使用分组的独立域名 | ||
| - | - | 将与每条API的请求路径拼接起来使用 | 未填充 | |
| API请求路径 | 与basePath拼接起来作为API请求路径 | 填充为API请求路径 | ||
| API名称 | 作为API名称 | 填充为API名称 | ||
| API描述 | 作为API描述 | 填充为API描述 | ||
| API前端请求参数 | 作为API请求参数 | 填充为API请求参数 | ||
| - | API前端请求协议 | 作为API请求协议 | 填充为API请求协议 | |
| - | 未使用 | 固定填充default响应定义 | ||
| API认证方式 | API认证方式 | 填充为API认证方式 |
父主题： 导入导出API
