广告位

Api网关通过导入Swagger文件创建和更新Api的功能已经上线了，更多帅气功能会逐步推出
Api网关目标是让您发布应用更加便捷和安全，让您更直观、便捷的管理和调试您的所有Api接口
欢迎试用阿里云Api网关产品，任何问题可以加Ding群讨论：11747055

1. 什么是swagger

微服务现在在商业引用程序开发中，已经广泛使用。而Api作为连接微服务之间的桥梁扮演着至关重要的角色。如何可以更清晰的描述微服务接口、如何可以更便捷便捷的管理Api，已经成为开发人员呼声很高的需求。而作为设计和管理api的利器，Swagger也随之成为了热门。

Swagger出现在2010年，它设计的初衷在于制定一种简单的规范，用于设计Api。Swagger文件可用于开发人员后期维护和管理。随着不断的发展，基于swagger规范，已经衍生出很多工具，用于辅助创建和管理Swagger文件，并已经形成了Swagger生态。用户可以通过Swagger工具来对api的整个生命周期进行设计，管理以及测试等操作。Swagger规范现在已经改名为Openapi规范，它将作为一种定义api管理的规范不断的完善与发展。

2. Api网关的定位

Api网关产品，可以为企业和个人提供完成的API托管服务。用户可以直接使用Api网关提供的认证、流控和监控等功能而无需自行开发。这样，用户就可以更专注于开发和实现自己的后端业务系统，而省去很多系统通用但是不可或缺的功能组件的开发工作。

接入Api网关通常需要如下步骤：

1. 定义Api基本属性，如Api名称，认证方式，基本描述等。
2. 配置Api访问相关属性，用于设置暴露给第三方的访问参数等
3. 配置APi后端相关属性，用于设置真正的后端服务地址，以及参数信息，超时时间等

通过这些配置，就可以完成api在Api网关的接入工作了。具体参考官方文档：Api网关使用须知

3. Swagger基于阿里云Api网关的扩展

与Swagger相同，阿里云Api网关具备Api管理的功能。除此之外，Api网关提供了身份认证，防重放，请求加密以及流量控制等功能。对于用户而言，如果可以将本地用Swagger管理的Api托管至Api网关，在一定程度将会有很大的增益。

因为Swagger与Api网关的定位不同，原生的Swagger文件并不能够直接导入Api网关用来创建Api。详细来说，Swagger通常用于定义和管理真实的服务Api，所以其定义的“访问相关属性”均为服务实际Api的属性，如服务的地址以及传入的参数。因此，Swagger并无类似于“Api后端相关”的属性。而对于Api网关，参数映射及后端服务地址保护是其不可或缺的特性。对此，阿里云Api网关实现了一些Swagger扩展，让用户只需对原生swagger进行简单修改，便能够将其swagger管理的api托管至Api网关进行管理，并享有Api网关提供的所有功能特性。

Swagger扩展主要是对于swagger原生Operation Object进行扩展，增加认证、参数映射以及后端服务等扩展。所有扩展均以x-aliyun-apigateway-开头，具体扩展内容如下：

3.1 x-aliyun-apigateway-auth-type: 授权类型

授权类型，应用于Operation Object。用于指定该API的授权类型，其中：

取值范围:

• APP(默认值): 阿里云API网关APP授权
• ANONYMOUS: 匿名

示例：

... paths: 'path/': get: x-aliyun-apigateway-auth-type: ANONYMOUS ...

3.2 x-aliyun-apigateway-paramater-handling: API映射关系

API映射关系, 应用于Operation Object，用于指定请求参数与后端服务参数的映射关系。当映射关系选择PASSTHROUGH时，Parameter Object不支持 x-aliyun-apigateway-backend-location 和 x-aliyun-apigateway-backend-name 属性。

取值范围:

• PASSTHROUGH(默认值): 入参透传
• MAPPING: 入参映射

示例：

... paths: 'path/': get: x-aliyun-apigateway-paramater-handling: MAPPING ...

3.3 x-aliyun-apigateway-backend: 后端类型

后端类型, 应用于Operation Object。用于设置后端服务信息。根据后端服务类型，决定具体的属性，详情如下：

1.3.1 后端服务类型:HTTP

HTTP的后端类型用于直接配置后端服务地址，一般用于后端地址可以直接访问的场合。

属性说明:

属性名称	类型	描述
type	string	必填；值为HTTP
address	string	必填；用于标识后端服务地址
path	string	必填:用于标识后端服务路径。支持路径变量
method	string	必填：后端请求方法
timeout	int	选填，默认为10000。该属性取值范围为[500,30000]

示例:

... x-aliyun-apigateway-backend: type: HTTP address: http://10.10.100.2:8000 path: "/users/{userId}" method: GET timeout: 7000 ...

3.3.2 后端服务类型:HTTP-VPC

HTTP-VPC的后端类型用于后端服务在VPC网络内的场合，需要先创建VPC授权，使用VPC授权名导入。

属性说明:

属性名称	类型	描述
type	string	必填；值为：HTTP-VPC
vpcAccessName	string	必填；后端服务使用的vpc实例名称
path	string	必填:用于标识后端服务路径。支持路径变量
method	string	必填：后端请求方法
timeout	int	选填，默认为10000。该属性取值范围为[500,30000]

示例:

... x-aliyun-apigateway-backend: type: HTTP_VPC vpcAccessName: vpcAccess1 path: "/users/{userId}" method: GET timeout: 10000 ...

3.3.3 后端服务类型: MOCK

MOCK的后端类型，用来模拟最初预定的返回结果。

属性说明:

属性名称	类型	描述
type	string	必填；值为:MOCK
mockResult	string	必填；mock返回结果
mockStatusCode	Integer	选填
mockHeaders	Header	选填

Header 的 说明

属性名称	类型	描述
name	string	必填
value	string	必填

示例:

... x-aliyun-apigateway-backend: type: MOCK mockResult: mock resul sample mockStatusCode ：200 mockHeaders ： - name : server value : mock - name : proxy value : GW ...

3.4 x-aliyun-apigateway-constant-parameters: 常量参数

常量参数, 应用于Operation Object，用于定义后端服务的常量参数。

属性说明:

属性名称	类型	描述
backendName	string	必填；后端参数名称
value	string	必填；常量值
location	String	必填；常量参数存放位置，可选值:[query,header]
description	string	可选；用于对该常量进行说明

示例:

 ... x-aliyun-apigateway-constant-parameters: - backendName: swaggerConstant value: swaggerConstant location: header description: description of swagger ...

3.5 x-aliyun-apigateway-system-parameters： 后端服务参数

后端服务参数, 应用于Operation Object，用于定义API后端服务的系统参数。

属性说明:

属性名称	类型	描述
systemName	string	必填；系统参数名称
backendName	string	必填；后端参数名称
location	String	必填；常量参数存放位置，可选值:[query,header]

示例:

 ... x-aliyun-apigateway-system-parameters: - systemName: CaAppId backendName: appId location: header ... 

3.6 x-aliyun-apigateway-backend-location: 后端参数位置

后端参数位置, 应用于 Parameter Object。该属性仅在 x-aliyun-apigateway-paramater-handling: MAPPING设置时生效，用于设置参数映射后，在后端服务请求时的参数位置。

取值范围:

• path
• header
• query
• formData

示例:

 ... parameters: - name: swaggerHeader in: header required: false type: number format: double minimum: 0.1 maximum: 0.5 x-aliyun-apigateway-backend-location: query x-aliyun-apigateway-backend-name: backendQuery ...

3.7 x-aliyun-apigateway-backend-name: 后端参数名称

后端参数名称, 应用于Parameter Object。该属性仅在 x-aliyun-apigateway-paramater-handling: MAPPING设置时生效，用于设置参数映射后，在后端服务请求时的参数名称。

示例:

 ... parameters: - name: swaggerHeader in: header required: false type: number format: double minimum: 0.1 maximum: 0.5 x-aliyun-apigateway-backend-location: query x-aliyun-apigateway-backend-name: backendQuery ...

4. 基于阿里云api网关扩展的Swagger示例

第三节我们对Api网关的Swagger扩展进行了介绍，这里我们提供一个后端服务为Mock类型的示例帮助用户对Swagger文件的配置有更明确的了解

swagger: '2.0' basePath: / info: version: '0.9' title: Aliyun Api Gateway Swagger Sample schemes: - http paths: '/mock/get/mapping/{userId}': get: operationId: case1 schemes: - http - https x-aliyun-apigateway-paramater-handling: MAPPING x-aliyun-apigateway-backend: type: MOCK mockResult: mock resul sample mockStatusCode ：200 mockHeaders ： - name : server value : mock - name : proxy value : GW parameters: - name: userId in: path required: true type: string responses: '200': description: 200 description '400': description: 400 description

5. 通过导入Swagger创建和更新Api

Api网关可以通过两种方式导入Swagger并创建或者更新Api，分别为：Aliyun Openapi导入和web控制台导入。

5.1 ImportSwagger接口使用

通过调用ImportSwagger接口，可以通过导入符合阿里云swagger规范的文本内容创建API：

请求参数

名称	类型	是否必须	描述
Action	String	是	操作接口名，取值：ImportSwagger
GroupId	String	是	swagger将被导入的分组编号
Overwrite	Boolean	是	是否覆盖现有API。覆盖检测条件为: API的http请求类型+后端请求路径相同
DataFormat	String	是	swagger文本格式： json yaml
Data	String	是	swagger文本内容。详情请查看：通过Swagger导入API

返回参数

名称	数据类型	描述
RequestId	String	本次请求编号
Success	ApiImportSwaggerSuccess	本次所有通过swagger导入成功的API信息
Failed	ApiImportSwaggerFailed	本次所有通过swagger导入失败的API信息

对象说明

ApiImportSwaggerSuccess

对象属性名称	对象属性类型	描述
Path	String	创建API时配置的请求路径
Method	String	创建API时配置的http方法
ApiUid	String	导入成功的API的UID
ApiOperation	String	该API是创建（CREATE）或修改（MODIFY）

ApiImportSwaggerFailed

对象属性名称	对象属性类型	描述
Path	String	创建API时配置的请求路径
Method	String	创建API时配置的http方法
ErrorMsg	String	创建API时返回的错误信息

5.2 通过Web控制台导入Swagger

在Api管理界面，我们可以找到导入Swagger的入口，见下图:

点击导入Swagger进入Swagger导入界面，按照填写相应信息就可以完成Swagger的导入工作。控制台右方会返回最终api的创建结果：

6. 总结

以上就是阿里云Api网关对swagger文件的支持情况。现在用户可以通过配置基于Aliyun Api网关扩展的Swagger文件创建Api，可以方便的将本地Swagger文件管理的api托管至Api网关管理。但当前Swagger扩展并不能完全覆盖Api网关的所有功能，后续还会进行完善和升级，提高更好的便利性和友好度。

---

Reference