广告位
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网关通常需要如下步骤：
- 定义Api基本属性，如Api名称，认证方式，基本描述等。
- 配置Api访问相关属性，用于设置暴露给第三方的访问参数等
- 配置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文本格式：
|
| 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的创建结果：
![控制台swagger]( "控制台swagger")
6. 总结
以上就是阿里云Api网关对swagger文件的支持情况。现在用户可以通过配置基于Aliyun Api网关扩展的Swagger文件创建Api，可以方便的将本地Swagger文件管理的api托管至Api网关管理。但当前Swagger扩展并不能完全覆盖Api网关的所有功能，后续还会进行完善和升级，提高更好的便利性和友好度。
Reference
