API的导入导出
更新时间：2021-07-02
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 |
配置示例
Plain Text
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验证（默认）
示例
Plain Text
1x-bce-apigw-auth:APPx-bce-apigw-api-id
应用于Operation Object。API的uuid，当导入模式为更新时配置生效，用于指定更新的api。只在单个api配置中生效，不存在全局配置。
子配置项
- 无
取值
- API uuid，需要修改的API的uuid
示例
Plain Text
1x-bce-apigw-api-id:GWAI-pxCkY5sLyMmx-bce-apigw-mkt-enable
应用于Operation Object。用于指定该API是否允许上架云市场。
子配置项
- 无
取值
- false：不允许（默认）
- true：允许
示例
Plain Text
1x-bce-apigw-mkt-enable:truex-bce-apigw-request-mode
应用于Operation Object。用于指定query参数与后端服务参数的映射关系。没有此配置时，当有参数配置，则默认为映射；没有参数配置，则默认为透传。三个自选项不是必须都存在，依据需要配置即可。
子配置项
- path
- query
- header
- body
取值
- PASSTHROUGH：透传
- MAPPING：映射
示例
Plain Text
1x-bce-apigw-requestmode:
2 query:PASSTHROUGH
3 header:MAPPINGx-bce-apigw-request-type
应用于Operation Object。用于指定body参数与后端服务参数的映射关系。
子配置项
- 无
取值
- FORM（默认）：表示请求体为“application/x-www-form-urlencoded”格式。
- STREAM：表示请求题为非form格式。比如请求体是二进制文件等，网关不支持映射该格式的body参数。
示例
Plain Text
1x-bce-apigw-requestmode:FROMx-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 | 是 | 参数类型 |
取值
Plain Text
1无示例
Plain Text
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:BceAppIdx-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
示例
Plain Text
1x-bce-apigw-backend-response-content-type: JSONx-bce-apigw-backend-mapping
应用于Parameter Object。用于设置后端请求参数的映射。子配置根据需要进行配置，不需要都配置。
子配置项
- location：该属性仅在 x-bce-apigw-requestmode的子配置项配置为MAPPING设置时生效，用于设置参数映射后，在后端服务请求时的参数位置。取值为：path、header、query
- name：该属性仅在 x-bce-apigw-requestmode的子配置项配置为MAPPING设置时生效，用于设置参数映射后，在后端服务请求时的参数名称。如果不设置，采用与请求参数相同的名字
取值
- 请见上方子配置项说明
示例
Plain Text
1x-bce-apigw-backend-mapping:
2 location:query
3 name:newnamex-bce-apigw-request-param
应用于Parameter Object。用于设置网关请求参数的校验。子配置根据需要进行配置，不需要都配置。
子配置项
- fixed：用于设置入参为固定值类型。与参数属性“required=true”不应该同时存在。true 表示为固定参数
- fixed-value：用于设置入参的固定值。只有当x-bce-apigw-request-param的子配置项fixed为true时生效。该配置不应与默认值同时存在。
- check：用于设置入参的参数检查。
- json-check：用于设置入参的json校验。
取值
- 请见上方子配置项说明
示例
Plain Text
1x-bce-apigw-request-param:
2 fixed:true
3 fixed-value:5x-bce-apigw-any-method:
应用于Path Item Object，用于设置API可以接受任意类型的http请求。
子配置项
- 无
取值
- 无
示例
Plain Text
1x-bce-apigw-any-method:x-bce-apigw-backend-error-msg
应用于Response Object，由于网关要求错误的返回必须带有code，message和description。所以对于4xx和5xx的返回，必须配置该字段。
子配置项
- 无
取值
- 无
示例
Plain Text
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配置示例，您可以参考该示例使用扩展字段。
Plain Text
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