API的导入导出

Updated at：2025-08-20

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:APP

x-bce-apigw-api-id

应用于Operation Object。API的uuid，当导入模式为更新时配置生效，用于指定更新的api。只在单个api配置中生效，不存在全局配置。

子配置项

取值

API uuid，需要修改的API的uuid

示例

Plain Text

1x-bce-apigw-api-id:GWAI-pxCkY5sLyMm

x-bce-apigw-mkt-enable

应用于Operation Object。用于指定该API是否允许上架云市场。

子配置项

取值

false：不允许（默认）
true：允许

示例

Plain Text

1x-bce-apigw-mkt-enable:true

x-bce-apigw-request-mode

应用于Operation Object。用于指定query参数与后端服务参数的映射关系。没有此配置时，当有参数配置，则默认为映射；没有参数配置，则默认为透传。三个自选项不是必须都存在，依据需要配置即可。

子配置项

path
query
header
body

取值

PASSTHROUGH：透传
MAPPING：映射

示例

Plain Text

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参数。

示例

Plain Text

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	是	参数类型

取值

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: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

示例

Plain Text

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设置时生效，用于设置参数映射后，在后端服务请求时的参数名称。如果不设置，采用与请求参数相同的名字

取值

请见上方子配置项说明

示例

Plain Text

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校验。

取值

请见上方子配置项说明

示例

Plain Text

1x-bce-apigw-request-param:
2  fixed:true
3  fixed-value:5

x-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:integer format:int32	int
type:integer format:int64	long
type:number format:float	float
type:number format:double	double
type:boolean format: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

流控管理

Model管理

API网关 APIGW

API网关 APIGW

API的导入导出

导出功能

导入功能

API网关自定义格式的导入

Swagger格式yaml导入

Swagger扩展说明

必要扩展

x-bce-apigw-backend-services

非必要扩展

x-bce-apigw-auth

x-bce-apigw-api-id

x-bce-apigw-mkt-enable

x-bce-apigw-request-mode

x-bce-apigw-request-type

x-bce-apigw-backend-params

x-bce-apigw-backend-request-content-type

x-bce-apigw-backend-response-content-type

x-bce-apigw-backend-mapping

x-bce-apigw-request-param

x-bce-apigw-any-method:

x-bce-apigw-backend-error-msg

说明

类型转换说明

整体示例