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 |
配置示例
x-bce-apigw-backend-services:
path: '/a'
timeout: 80000
method: any
type: HTTP
hosts:
- address: 'http://baidu.com'
qps: 200
region: DEFAULT
subType: INSTANCE非必要扩展
本部分扩展为非必须扩展，您可以根据自己的API配置进行增加，如果不填写，网关会有相应的默认值进行填充。
x-bce-apigw-auth
应用于Operation Object。用于指定该API的授权类型。
子配置项
- 无
取值
- ANONYMOUS：无验证
- APP：APP的ak、sk验证（默认）
示例
x-bce-apigw-auth:APPx-bce-apigw-api-id
应用于Operation Object。API的uuid，当导入模式为更新时配置生效，用于指定更新的api。只在单个api配置中生效，不存在全局配置。
子配置项
- 无
取值
- API uuid，需要修改的API的uuid
示例
x-bce-apigw-api-id:GWAI-pxCkY5sLyMmx-bce-apigw-mkt-enable
应用于Operation Object。用于指定该API是否允许上架云市场。
子配置项
- 无
取值
- false：不允许（默认）
- true：允许
示例
x-bce-apigw-mkt-enable:truex-bce-apigw-request-mode
应用于Operation Object。用于指定query参数与后端服务参数的映射关系。没有此配置时，当有参数配置，则默认为映射；没有参数配置，则默认为透传。三个自选项不是必须都存在，依据需要配置即可。
子配置项
- path
- query
- header
- body
取值
- PASSTHROUGH：透传
- MAPPING：映射
示例
x-bce-apigw-requestmode:
query:PASSTHROUGH
header:MAPPINGx-bce-apigw-request-type
应用于Operation Object。用于指定body参数与后端服务参数的映射关系。
子配置项
- 无
取值
- FORM（默认）：表示请求体为“application/x-www-form-urlencoded”格式。
- STREAM：表示请求题为非form格式。比如请求体是二进制文件等，网关不支持映射该格式的body参数。
示例
x-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 | 是 | 参数类型 |
取值
无示例
x-bce-apigw-backend:
constant-params:
- name:constanttest
value:5
location:query
type:String
system-para:
- name:systemtest
location:head
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
示例
x-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设置时生效，用于设置参数映射后，在后端服务请求时的参数名称。如果不设置，采用与请求参数相同的名字
取值
- 请见上方子配置项说明
示例
x-bce-apigw-backend-mapping:
location:query
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校验。
取值
- 请见上方子配置项说明
示例
x-bce-apigw-request-param:
fixed:true
fixed-value:5x-bce-apigw-any-method:
应用于Path Item Object，用于设置API可以接受任意类型的http请求。
子配置项
- 无
取值
- 无
示例
x-bce-apigw-any-method:x-bce-apigw-backend-error-msg
应用于Response Object，由于网关要求错误的返回必须带有code，message和description。所以对于4xx和5xx的返回，必须配置该字段。
子配置项
- 无
取值
- 无
示例
x-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配置示例，您可以参考该示例使用扩展字段。
swagger: '2.0'
basePath: /
info:
version: '0.9'
title: BCE Api Gateway Swagger Sample
schemes:
- http
- https
x-bce-apigw-auth: APP
x-bce-apigw-mkt-enable: false
x-bce-apigw-backend-services:
path: '/a'
timeout: 80000
method: any
type: HTTP
hosts:
- address: 'http://baidu.com'
qps: 200
region: DEFAULT
subType: INSTANCE
paths:
'/swagger/apigw/get/{userId}':
get:
operationId: swaggerget
schemes:
- http
- https
x-bce-apigw-request-mode:
header: MAPPING
x-bce-apigw-mkt-enable: true
x-bce-apigw-api-id: GWAI-pxCkY5sLyMm
x-bce-apigw-auth: APP
parameters:
- name: userId
in: path
required: true
type: string
- name: swaggerQuery
in: query
required: false
type: integer
format: int32
minimum: 0
maximum: 100
x-bce-apigw-request-param:
fixed: true
fixed-value: 12
- name: swaggerHeader
in: header
required: false
type: number
format: double
minimum: 0.1
maximum: 0.5
x-bce-apigw-backend-mapping:
location: query
name: backendQuery
x-bce-apigw-backend-params:
constant-params:
- name: swaggerConstant
value: swaggerConstant
location: header
type: STRING
system-params:
- name: BceAppId
location: header
type: BceAppId
x-bce-apigw-backend-response-content-type: JSON
x-bce-apigw-backend-services:
type: MOCK
mockStatusCode: 200
mockResult: 2
mockHeaders:
- name: mockHeader
value: mock
responses:
'200':
description: 200 description
'400':
description: 400 description
x-bce-apigw-backend-error-msg: 4XX error
'/swagger/apigw/postany/{userId}':
post:
operationId: swaggerpost
schemes:
- http
- https
x-bce-apigw-request-mode:
header: MAPPING
query: MAPPING
consumes:
- application/x-www-form-urlencoded
parameters:
- name: userId
required: true
in: path
type: string
x-bce-apigw-backend-mapping:
location: query
name: path2query
- name: swaggerQuery1
in: query
required: false
default: '1'
type: integer
format: int32
minimum: 0
maximum: 100
enum: [1,2,3]
- name: swaggerQuery2
in: query
required: false
type: string
- name: swaggerHeader
in: header
required: false
type: number
format: double
minimum: 0.1
maximum: 0.5
x-bce-apigw-backend-mapping:
location: query
name: headtoquery
- name: swaggerBody
in: formData
required: true
type: string
x-bce-apigw-backend-mapping:
location: query
name: bodytoquery
responses:
'200':
description: 200 description
'400':
description: 400 description
x-bce-apigw-backend-error-msg: 4XX error
x-bce-apigw-any-method:
operationId: swaggerany
x-bce-apigw-request-mode:
header: MAPPING
schemas:
- http
- https
x-bce-apigw-backend-services:
path: '/a/{userId}'
timeout: 80000
method: any
type: HTTP
hosts:
- address: 'http://baidu.com'
qps: 200
region: DEFAULT
subType: INSTANCE
parameters:
- name: userId
in: path
required: true
default: '123465'
type: integer
format: int32
minimum: 0
maximum: 100
- name: swaggerHeader
in: header
required: false
type: number
format: double
minimum: 0.1
maximum: 0.5
x-bce-apigw-backend-mapping:
location: query
name: anyheader
responses:
'200':
description: 200 description
'400':
description: 400 description
x-bce-apigw-backend-error-msg: 4XX error
'/swagger/apigw/vpc/{userId}':
get:
operationId: vpc
schemes:
- http
- https
x-bce-apigw-request-mode:
header: MAPPING
x-bce-apigw-mkt-enable: true
x-bce-apigw-auth: APP
parameters:
- name: userId
in: path
required: true
type: string
- name: swaggerQuery
in: query
required: false
type: integer
format: int32
minimum: 0
maximum: 100
x-bce-apigw-request-param:
fixed: true
fixed-value: 12
- name: swaggerHeader
in: header
required: false
type: number
format: double
minimum: 0.1
maximum: 0.5
x-bce-apigw-backend-mapping:
location: query
name: backendQuery
x-bce-apigw-backend-params:
constant-params:
- name: swaggerConstant
value: swaggerConstant
location: header
type: STRING
system-params:
- name: BceAppId
location: header
type: BceAppId
x-bce-apigw-backend-response-content-type: JSON
x-bce-apigw-backend-services:
path: '/a/{userId}'
timeout: 80000
method: any
type: HTTP
hosts:
- address: 'vpc-gk9p7gq8q6xf:192.168.1.1:8'
qps: 200
region: bj
subType: VPC
responses:
'200':
description: 200 description
'400':
description: 400 description
x-bce-apigw-backend-error-msg: 4XX error
'/swagger/apigw/websocket/{userId}':
get:
operationId: swaggerwesocket
schemes:
- ws
x-bce-apigw-backend-services:
path: '/a'
timeout: 80000
method: get
type: WEBSOCKET
hosts:
- address: 'ws://baidu.com'
qps: 200
region: DEFAULT
subType: INSTANCE
x-bce-apigw-request-mode:
header: MAPPING
query: MAPPING
consumes:
- application/x-www-form-urlencoded
parameters:
- name: userId
required: true
in: path
type: string
x-bce-apigw-backend-mapping:
location: query
name: path2query
- name: swaggerQuery1
in: query
required: false
default: '1'
type: integer
format: int32
minimum: 0
maximum: 100
enum: [1,2,3]
- name: swaggerQuery2
in: query
required: false
type: string
- name: swaggerHeader
in: header
required: false
type: number
format: double
minimum: 0.1
maximum: 0.5
x-bce-apigw-backend-mapping:
location: query
name: headtoquery
responses:
'200':
description: 200 description
'400':
description: 400 description
x-bce-apigw-backend-error-msg: 400 error