API的导入导出
API网关支持API的导入导出,导出功能目前只支持API网关自定义的yaml格式导出,导入功能支持API网关自定义的yaml格式导入和swagger格式的导入。
下面针对API网关的导入导出功能进行说明。
导出功能
导出功能目前只支持API网关自定义的yaml格式导出。您可以在console界面中API管理界面选择想要导出的API后进行导出:
您也可以在分组管理界面中将整个分组的API全部导出:
导入功能
您可以在分组管理和API管理页面进行API的导入:
导入功能支持API网关自定义的yaml格式导入和swagger格式的导入,进行导入时可以选择导入模式,API网关导入功能支持三种模式,分别为:
- 新增模式:忽略冲突 API。用于在分组内新增 API,如果遇到与已有 API 冲突的情况,会忽略该 API 的导入。
- 覆盖模式:覆盖冲突 API。导入 API 时,如果遇到与已有 API 冲突的情况,则覆盖已有 API。可用于恢复分组 API 快照等场景。
- 更新模式:只更新已有 API。若有冲突则忽略对应 API 的导入。使用该模式,需要在将要导入的 API 定义中,为每个 API 指定其在分组中的 API ID。
您可以根据需要选择导入模式。
API网关自定义格式的导入
针对导入导出,API网关有一套自定义的yaml格式,您可以将API导出然后在另外一个分组进行导入,此时您不需要进行额外的配置或修改,直接导入即可,在导入界面将导入格式选择为yaml格式即为使用API网关自定义yaml进行导入,而分组名称表示您要将API导入的分组:
Swagger格式yaml导入
Swagger是一种用于描述API定义的规范,被广泛应用于定义和描述后端应用服务的API。现在,API网关支持导入Swagger 2.0的文件(目前只支持yaml格式)来导入API。 为了适配API网关的API定义,我们对Swagger进行了扩展,API网关的Swagger扩展基于Swagger 2.0,可以创建API实体的Swagger定义,并将Swagger导入API网关用于批量创建或者更新API实体。
本章节主要对基于Swagger的API网关扩展进行介绍,并提供相应的示例来阐述用法。
Swagger扩展说明
API网关的Swagger扩展基于Swagger 2.0,可以创建API实体的Swagger定义,并将Swagger导入API网关用于批量创建或者更新API实体。
Swagger扩展主要是对于swagger原生Operation Object进行扩展,增加认证、参数映射以及后端服务等扩展。除此之外,增加处理any方法的扩展,用于捕获任意http(s)请求方法。 所有扩展均以x-bce-apigw-开头,具体扩展内容如下:
必要扩展
该类配置是用户在API网关导入API时必须进行的配置。
x-bce-apigw-backend-services
应用于Operation Object。用于设置后端服务信息。根据后端服务类型,决定具体的属性。因为网关支持多个后端,所以可以配置相同type的多个后端服务。而后端services有着多个共同属性,比如path、type等,下面针对x-bce-apigw-backend-services进行说明
公共属性(非mock类型):
属性名 | 类型 | 是否必填 | 说明 |
---|---|---|---|
type | String | 是 | 配置后端请求类型,分为HTTP、MOCK和WEBSOCKET(schemes请对应配置为ws) |
path | String | 是 | 配置后端请求的请求path,多个后端公用。 |
method | String | 是 | 配置后端请求的请求方法,多个后端公用。 |
timeout | String | 否 | 配置后端服务的超时时间,多个后端公用。 |
hosts | List<SwaggerBackendServer> |
是 | 配置后端服务的具体内容。 |
公共属性(mock类型):
属性名 | 类型 | 是否必填 | 说明 |
---|---|---|---|
mockResult | String | 是 | mock的返回结果 |
mockStatusCode | String | 否 | mock的状态码 |
mockHeaders | List<MockHeader> |
否 | mock的返回头 |
下面针对SwaggerBackendServer
和MockHeader
进行说明
SwaggerBackendServer
属性名 | 类型 | 是否必填 | 说明 |
---|---|---|---|
subType | String | 是 | 后端服务具体类型类型:INSTANCE:HTTP(s)或websocket实例VPC:vpc服务BNS:bns服务CFC:cfc服务 |
address | String | 是 | 后端服务地址 |
region | String | 否 | 区域,默认DEFAULT |
weight | int | 否 | 权重(默认值-1) |
qps | int | 否 | qps限制(默认值-1) |
MockHeader
属性名 | 类型 | 是否必填 | 说明 |
---|---|---|---|
key | String | 是 | header的key |
value | String | 是 | header的value |
配置示例
1x-bce-apigw-backend-services:
2 path: '/a'
3 timeout: 80000
4 method: any
5 type: HTTP
6 hosts:
7 - address: 'http://baidu.com'
8 qps: 200
9 region: DEFAULT
10 subType: INSTANCE
非必要扩展
本部分扩展为非必须扩展,您可以根据自己的API配置进行增加,如果不填写,网关会有相应的默认值进行填充。
x-bce-apigw-auth
应用于Operation Object。用于指定该API的授权类型。
子配置项
- 无
取值
- ANONYMOUS:无验证
- APP:APP的ak、sk验证(默认)
示例
1x-bce-apigw-auth:APP
x-bce-apigw-api-id
应用于Operation Object。API的uuid,当导入模式为更新时配置生效,用于指定更新的api。只在单个api配置中生效,不存在全局配置。
子配置项
- 无
取值
- API uuid,需要修改的API的uuid
示例
1x-bce-apigw-api-id:GWAI-pxCkY5sLyMm
x-bce-apigw-mkt-enable
应用于Operation Object。用于指定该API是否允许上架云市场。
子配置项
- 无
取值
- false:不允许(默认)
- true:允许
示例
1x-bce-apigw-mkt-enable:true
x-bce-apigw-request-mode
应用于Operation Object。用于指定query参数与后端服务参数的映射关系。没有此配置时,当有参数配置,则默认为映射;没有参数配置,则默认为透传。三个自选项不是必须都存在,依据需要配置即可。
子配置项
- path
- query
- header
- body
取值
- PASSTHROUGH:透传
- MAPPING:映射
示例
1x-bce-apigw-requestmode:
2 query:PASSTHROUGH
3 header:MAPPING
x-bce-apigw-request-type
应用于Operation Object。用于指定body参数与后端服务参数的映射关系。
子配置项
- 无
取值
- FORM(默认):表示请求体为“application/x-www-form-urlencoded”格式。
- STREAM:表示请求题为非form格式。比如请求体是二进制文件等,网关不支持映射该格式的body参数。
示例
1x-bce-apigw-requestmode:FROM
x-bce-apigw-backend-params
应用于Operation Object。用于定义后端服务的常量参数。
子配置项
- constant-params:用于定义后端的常量参数
- system-params:用于定义后端的系统参数
两个配置的详细说明 constant-params配置
属性名 | 类型 | 是否必填 | 说明 |
---|---|---|---|
name | String | 是 | 参数名 |
value | String | 是 | 值 |
location | String | 是 | 位置 |
type | String | 是 | 参数类型 |
system-params配置
属性名 | 类型 | 是否必填 | 说明 |
---|---|---|---|
name | String | 是 | 参数名 |
location | String | 是 | 位置 |
type | String | 是 | 参数类型 |
取值
1无
示例
1x-bce-apigw-backend:
2 constant-params:
3 - name:constanttest
4 value:5
5 location:query
6 type:String
7 system-para:
8 - name:systemtest
9 location:head
10 type:BceAppId
x-bce-apigw-backend-request-content-type
应用于Operation Object。用于定义后端请求值的content type。只有当body映射模式为MAPPING时生效。
子配置项
- category
- value
取值
- category取值:
CLIENT(默认):使用客户端的content type
CUSTOM:使用自定义的
DEFAULT:使用网关默认的 - value:当category选择为自定义时,必填。
x-bce-apigw-backend-response-content-type
应用于Operation Object。用于定义后端返回值的content type。
子配置项
- 无
取值
- JSON(默认):application/json;chartset=utf-8
- TEXT:text/plain;chartset=utf-8
- BINARY:application/octet-stream;chartset=utf-8
- XML:application/xml;chartset=utf-8
- HTML:text/html;chartset=utf-8
示例
1x-bce-apigw-backend-response-content-type: JSON
x-bce-apigw-backend-mapping
应用于Parameter Object。用于设置后端请求参数的映射。子配置根据需要进行配置,不需要都配置。
子配置项
- location:该属性仅在 x-bce-apigw-requestmode的子配置项配置为MAPPING设置时生效,用于设置参数映射后,在后端服务请求时的参数位置。取值为:path、header、query
- name:该属性仅在 x-bce-apigw-requestmode的子配置项配置为MAPPING设置时生效,用于设置参数映射后,在后端服务请求时的参数名称。如果不设置,采用与请求参数相同的名字
取值
- 请见上方子配置项说明
示例
1x-bce-apigw-backend-mapping:
2 location:query
3 name:newname
x-bce-apigw-request-param
应用于Parameter Object。用于设置网关请求参数的校验。子配置根据需要进行配置,不需要都配置。
子配置项
- fixed:用于设置入参为固定值类型。与参数属性“required=true”不应该同时存在。true 表示为固定参数
- fixed-value:用于设置入参的固定值。只有当x-bce-apigw-request-param的子配置项fixed为true时生效。该配置不应与默认值同时存在。
- check:用于设置入参的参数检查。
- json-check:用于设置入参的json校验。
取值
- 请见上方子配置项说明
示例
1x-bce-apigw-request-param:
2 fixed:true
3 fixed-value:5
x-bce-apigw-any-method:
应用于Path Item Object,用于设置API可以接受任意类型的http请求。
子配置项
- 无
取值
- 无
示例
1x-bce-apigw-any-method:
x-bce-apigw-backend-error-msg
应用于Response Object,由于网关要求错误的返回必须带有code,message和description。所以对于4xx和5xx的返回,必须配置该字段。
子配置项
- 无
取值
- 无
示例
1x-bce-apigw-backend-error-msg: 400 error
说明
- 关于swagger自带字段的使用: 参数的描述请使用swagger自带的description字段;参数默认值请使用swagger自带的enum字段。以上字段的使用请参考swagger2.0官方文档:swagger关于parameter说明。
- 网关仅支持form格式body参数进行映射,其他格式(json、二进制文件)等不支持映射,仅支持透传。当Swagger配置文件存在formdata类型参数时,需要配置consumes节点。API网关现在只支持application/x-www-form-urlencoded类型。其他类型body应适应swagger 的body进行标记并且body选择透传。
- 针对映射配置,没有具体的配置时,当有参数配置,则默认为映射;没有参数配置,则默认为透传。
- 暂时不支持全局的parameter和response配置,这两个配置请放在具体的api中。
类型转换说明
网关与Swagger规范在定义数据类型时存在一定差异性,包括:
swagger数据类型 | 网关数据类型 |
---|---|
type:integerformat:int32 | int |
type:integerformat:int64 | long |
type:numberformat:float | float |
type:numberformat:double | double |
type:booleanformat:Boolean | boolean |
type:string | String |
整体示例
为了能够完整说明各个扩展,现提供一个完整的API配置示例,您可以参考该示例使用扩展字段。
1swagger: '2.0'
2basePath: /
3info:
4 version: '0.9'
5 title: BCE Api Gateway Swagger Sample
6schemes:
7 - http
8 - https
9x-bce-apigw-auth: APP
10x-bce-apigw-mkt-enable: false
11x-bce-apigw-backend-services:
12 path: '/a'
13 timeout: 80000
14 method: any
15 type: HTTP
16 hosts:
17 - address: 'http://baidu.com'
18 qps: 200
19 region: DEFAULT
20 subType: INSTANCE
21paths:
22 '/swagger/apigw/get/{userId}':
23 get:
24 operationId: swaggerget
25 schemes:
26 - http
27 - https
28 x-bce-apigw-request-mode:
29 header: MAPPING
30 x-bce-apigw-mkt-enable: true
31 x-bce-apigw-api-id: GWAI-pxCkY5sLyMm
32 x-bce-apigw-auth: APP
33 parameters:
34 - name: userId
35 in: path
36 required: true
37 type: string
38 - name: swaggerQuery
39 in: query
40 required: false
41 type: integer
42 format: int32
43 minimum: 0
44 maximum: 100
45 x-bce-apigw-request-param:
46 fixed: true
47 fixed-value: 12
48 - name: swaggerHeader
49 in: header
50 required: false
51 type: number
52 format: double
53 minimum: 0.1
54 maximum: 0.5
55 x-bce-apigw-backend-mapping:
56 location: query
57 name: backendQuery
58 x-bce-apigw-backend-params:
59 constant-params:
60 - name: swaggerConstant
61 value: swaggerConstant
62 location: header
63 type: STRING
64 system-params:
65 - name: BceAppId
66 location: header
67 type: BceAppId
68 x-bce-apigw-backend-response-content-type: JSON
69 x-bce-apigw-backend-services:
70 type: MOCK
71 mockStatusCode: 200
72 mockResult: 2
73 mockHeaders:
74 - name: mockHeader
75 value: mock
76 responses:
77 '200':
78 description: 200 description
79 '400':
80 description: 400 description
81 x-bce-apigw-backend-error-msg: 4XX error
82 '/swagger/apigw/postany/{userId}':
83 post:
84 operationId: swaggerpost
85 schemes:
86 - http
87 - https
88 x-bce-apigw-request-mode:
89 header: MAPPING
90 query: MAPPING
91 consumes:
92 - application/x-www-form-urlencoded
93 parameters:
94 - name: userId
95 required: true
96 in: path
97 type: string
98 x-bce-apigw-backend-mapping:
99 location: query
100 name: path2query
101 - name: swaggerQuery1
102 in: query
103 required: false
104 default: '1'
105 type: integer
106 format: int32
107 minimum: 0
108 maximum: 100
109 enum: [1,2,3]
110 - name: swaggerQuery2
111 in: query
112 required: false
113 type: string
114 - name: swaggerHeader
115 in: header
116 required: false
117 type: number
118 format: double
119 minimum: 0.1
120 maximum: 0.5
121 x-bce-apigw-backend-mapping:
122 location: query
123 name: headtoquery
124 - name: swaggerBody
125 in: formData
126 required: true
127 type: string
128 x-bce-apigw-backend-mapping:
129 location: query
130 name: bodytoquery
131 responses:
132 '200':
133 description: 200 description
134 '400':
135 description: 400 description
136 x-bce-apigw-backend-error-msg: 4XX error
137 x-bce-apigw-any-method:
138 operationId: swaggerany
139 x-bce-apigw-request-mode:
140 header: MAPPING
141 schemas:
142 - http
143 - https
144 x-bce-apigw-backend-services:
145 path: '/a/{userId}'
146 timeout: 80000
147 method: any
148 type: HTTP
149 hosts:
150 - address: 'http://baidu.com'
151 qps: 200
152 region: DEFAULT
153 subType: INSTANCE
154 parameters:
155 - name: userId
156 in: path
157 required: true
158 default: '123465'
159 type: integer
160 format: int32
161 minimum: 0
162 maximum: 100
163 - name: swaggerHeader
164 in: header
165 required: false
166 type: number
167 format: double
168 minimum: 0.1
169 maximum: 0.5
170 x-bce-apigw-backend-mapping:
171 location: query
172 name: anyheader
173 responses:
174 '200':
175 description: 200 description
176 '400':
177 description: 400 description
178 x-bce-apigw-backend-error-msg: 4XX error
179 '/swagger/apigw/vpc/{userId}':
180 get:
181 operationId: vpc
182 schemes:
183 - http
184 - https
185 x-bce-apigw-request-mode:
186 header: MAPPING
187 x-bce-apigw-mkt-enable: true
188 x-bce-apigw-auth: APP
189 parameters:
190 - name: userId
191 in: path
192 required: true
193 type: string
194 - name: swaggerQuery
195 in: query
196 required: false
197 type: integer
198 format: int32
199 minimum: 0
200 maximum: 100
201 x-bce-apigw-request-param:
202 fixed: true
203 fixed-value: 12
204 - name: swaggerHeader
205 in: header
206 required: false
207 type: number
208 format: double
209 minimum: 0.1
210 maximum: 0.5
211 x-bce-apigw-backend-mapping:
212 location: query
213 name: backendQuery
214 x-bce-apigw-backend-params:
215 constant-params:
216 - name: swaggerConstant
217 value: swaggerConstant
218 location: header
219 type: STRING
220 system-params:
221 - name: BceAppId
222 location: header
223 type: BceAppId
224 x-bce-apigw-backend-response-content-type: JSON
225 x-bce-apigw-backend-services:
226 path: '/a/{userId}'
227 timeout: 80000
228 method: any
229 type: HTTP
230 hosts:
231 - address: 'vpc-gk9p7gq8q6xf:192.168.1.1:8'
232 qps: 200
233 region: bj
234 subType: VPC
235 responses:
236 '200':
237 description: 200 description
238 '400':
239 description: 400 description
240 x-bce-apigw-backend-error-msg: 4XX error
241 '/swagger/apigw/websocket/{userId}':
242 get:
243 operationId: swaggerwesocket
244 schemes:
245 - ws
246 x-bce-apigw-backend-services:
247 path: '/a'
248 timeout: 80000
249 method: get
250 type: WEBSOCKET
251 hosts:
252 - address: 'ws://baidu.com'
253 qps: 200
254 region: DEFAULT
255 subType: INSTANCE
256 x-bce-apigw-request-mode:
257 header: MAPPING
258 query: MAPPING
259 consumes:
260 - application/x-www-form-urlencoded
261 parameters:
262 - name: userId
263 required: true
264 in: path
265 type: string
266 x-bce-apigw-backend-mapping:
267 location: query
268 name: path2query
269 - name: swaggerQuery1
270 in: query
271 required: false
272 default: '1'
273 type: integer
274 format: int32
275 minimum: 0
276 maximum: 100
277 enum: [1,2,3]
278 - name: swaggerQuery2
279 in: query
280 required: false
281 type: string
282 - name: swaggerHeader
283 in: header
284 required: false
285 type: number
286 format: double
287 minimum: 0.1
288 maximum: 0.5
289 x-bce-apigw-backend-mapping:
290 location: query
291 name: headtoquery
292 responses:
293 '200':
294 description: 200 description
295 '400':
296 description: 400 description
297 x-bce-apigw-backend-error-msg: 400 error