概述

网关支持导入OAS2.0和OAS3.0格式的API定义，帮助用户快速将现有系统的API接入网关。API网关既支持标准OAS格式的API定义的导入、也支持OAS定义扩展后的API定义导入。

导入标准OAS格式的API定义

导入API的流程主要包括:

• 选择基本信息(必填)与全局配置(选填).
• 文本填写或文件导入OAS 2.0或OAS 3.0格式的API定义.
• 进行预检并根据检查结果进行调整.
• 执行导入,成功导入后会生成对应的API和分组模型.

对应控制台操作为:

1, 进入API托管->API管理菜单页.

2, 在API列表页点击导入Swagger按钮,进入API导入配置页面.
a. 基本信息,必填

b. 全局配置,选填.主要是对入参请求模式,防止重放攻击进行API全局设置。如果用户OAS定义中通过扩展字段填写了该配置信息,则优先使用用户配置.

c. API定义,确定计划导入的OAS定义内容，支持文本填入yaml或json格式的API定义内容,也支持上传本地API定义文件。

3, 单击预检按钮，系统将会对计划导入的内容进行检查，检测出OAS定义中的API定义和模型定义，以及告警和错误信息。

4, 预检过程中没有错误信息和警告信息（或者忽略警告信息之后），可执行导入。单击导入Swagger按钮，系统真正开始导入API，导入API需要一定时间，导入过程请勿关闭浏览器。

5, 待系统执行完毕后，可查看到API导入结果。

标准OAS2.0格式与API网关的对应

本章节重点介绍OAS 2.0的格式定义与网关的API定义有对应的映射字段，对于没有对应映射的OAS中的定义，不会影响API的导入。

1. Swagger Object：
   1. BasePath：对应分组的BasePath，导入时需要认证；
2. Path Item Object：
   1. Path：对应API定义中请求部分的请求path；
   2. Method：对应API定义中请求部分的Method，支持GET，POST，PUT，HEAD，DELETE，PATCH，OPTIONS；
3. Operation Object：
   1. Summary：对应API定义的描述；
   2. OperationId：对应API定义的API名称，如果存在扩展字段“x-ctyun-apigateway-api-name”则使用扩展字段中的内容作为API的名称；
   3. Schemes：对应API定义中请求部分支持的协议，优先级高于Swagger Object中的定义；
4. Parameter Object：
   1. Name：对应API定义中请求部分的参数名称；
   2. In：对应API定义中请求部分的参数位置，支持path，query，head，formdata；
   3. Description：对应API定义中请求部分的参数描述；
   4. Required：对应API定义中请求部分的参数是否必填；
5. Response Object：
   1. HTTP Status Code：对应API定义中定义返回结果中错误码定义中的错误码；
   2. Description：对应API定义中定义返回结果中错误码定义中的描述；
   3. Schema：对应API定义中定义返回结果中错误码定义中的模型；
6. Definitions Object：
   该项定义中的对象，在导入的过程中，API网关会将模型创建在分组下，查看模型定义可以通过分组管理列表下，对应分组的操作栏中的模型管理查看。

标准OAS3.0格式与API网关的对应

本章节重点介绍OAS 3.0的格式定义与API网关的API定义有对应的映射字段，对于没有对应映射的OAS中的定义，不会影响API的导入。

1. Path Item Object
   1. Path：对应API定义中请求部分的请求path；
   2. Method：对应API定义中请求部分的Method，支持GET，POST，PUT，HEAD，DELETE，PATCH，OPTIONS；
2. Operation Object
   1. Summary：对应API定义的描述；
   2. OperationId：对应API定义的API名称，如果存在扩展字段“x-ctyun-apigateway-api-name”则使用扩展字段中的内容作为API的名称；
3. Parameter Object
   1. Name：对应API定义中请求部分的参数名称；
   2. In：对应API定义中请求部分的参数位置，支持path，query，head，formdata；
   3. Required：对应API定义中请求部分的参数是否必填；
4. Schema Object：
   1. Description：对应API定义中请求部分的参数描述；
   2. Type：对应API定义中请求部分的参数类型；
5. Responses Object
   1. HTTP Status Code：对应API定义中定义返回结果中错误码定义中的错误码；
   2. Description：对应API定义中定义返回结果中错误码定义中的描述；
   3. Content：对应API定义中定义返回结果中错误码定义中的模型；

导入具有API网关扩展字段的OAS格式定义

swagger支持导入具有API网关扩展字段的OAS格式定义