Updated on 2022-04-14 GMT+08:00

Exporting Multiple APIs

Function

This API is used to export the basic, full, or extended Swagger definition of specified APIs by their IDs.

URI

The following table lists the HTTP/HTTPS request method and URI of the API.

Table 1

Request Method

URI

POST

/v1.0/apigw/openapi/apis?env_id={0}&define={2}&version={3}&type={4}

The following table lists the parameter in the URI.

Table 2 Parameter description

Parameter

Mandatory

Type

Description

env_id/env

Yes

String

ID of the environment where APIs in a specified group have been published. Both env_id (recommended) and env can indicate an environment ID. If the two parameters are available, the value of env_id takes the precedence.

define

No

String

Definition scope of the APIs to be exported:

  • base: basic definition
  • full: full definition
  • all: extended definition

The default value is base.

version

No

String

Version of the APIs after exporting. The default value is the current date and time.

type

No

String

Format for exporting API definitions. The value can be json or yaml. The default value is json.

Request

Table 3 Parameter description

Location

Mandatory

Type

Description

body

Yes

String Array

IDs of the APIs to be exported

Example request:

["81efcfd94b8747a0b21e8c04144a4e8c","7addcd00cfab433984b1d8bf2fe08aaa"]

Response

Table 4 Parameter description

Parameter

Mandatory

Type

Description

swagger

Yes

String

The value is fixed at 2.0.

info

Yes

Object

For details, see Table 5.

host

Yes

String

Subdomain name bound to the API group

paths

Yes

Object

See Table 6.

responses

Yes

Object

Common response, which can be referenced in {method}. For details, see Table 10.

securityDefinitions

Yes

Object

Security authentication mode definition. For details, see Table 14.

x-apigateway-access-controls

No

Object

Access control information. For details, see Table 23.

x-apigateway-ratelimits

No

Object

Request throttling information. For details, see Table 25.

Table 5 Parameter description of info

Parameter

Mandatory

Type

Description

title

Yes

String

API group name

version

Yes

String

Version number. You can specify a version number or use the current date and time by default.

description

No

String

Description of the API group

Table 6 Parameter description of paths

Parameter

Mandatory

Type

Description

uri

Yes

Object

API access address. For details, see Table 7.

Table 7 Parameter description of uri

Parameter

Mandatory

Type

Description

method

Yes

Object

API access method. For details, see Table 8.

Table 8 Parameter description of method

Parameter

Mandatory

Type

Description

operationId

Yes

String

API name

description

No

String

API description

schemes

Yes

Object

API request protocol. HTTP and HTTPS are supported.

tags

No

Object

API tags

parameters

No

Object

Request parameter definitions. For details, see Table 9.

responses

Yes

Object

Response definition. For details, see Table 10.

security

No

Object

Security authentication mode. For details, see Table 11.

x-apigateway-access-control

No

Object

Access control policy bound to the API

x-apigateway-backend

No

Object

Backend information. For details, see Table 16.

x-apigateway-backend-policies

No

Object

Backend policy information. For details, see Table 17.

x-apigateway-cors

No

Boolean

Indicates whether CORS is supported.

x-apigateway-match-mode

No

String

Route matching mode

x-apigateway-ratelimit

No

String

Name of the request throttling policy bound to the API

x-apigateway-request-type

No

String

API type

Table 9 Frontend parameter description

Parameter

Mandatory

Type

Description

maximum

No

Float

Maximum value of a number type parameter

minimum

No

Float

Minimum value of a number type parameter

maxLength

No

Integer

Maximum length of a string type parameter

minLength

No

Integer

Minimum length of a string type parameter

pattern

No

String

Regular expression of the parameter value

type

No

String

Type

default

No

String

Default value

description

No

String

Parameter description

name

No

String

Parameter name

in

No

String

Parameter location, which can be path, header, query, formData, or body

required

No

Boolean

Whether the parameter is required. The parameter is required when its location is path.

Table 10 Parameter description of responses

Parameter

Mandatory

Type

Description

default

No

Object

Default response, which will be used when no status codes are defined

status_code

No

Object

Response status code. The value is a response object. For details, see Table 12.

x-apigateway-result-failure-sample

No

String

Example response for a failed request

x-apigateway-result-normal-sample

No

String

Example response for a successful request

Table 11 Parameter description of security

Parameter

Mandatory

Type

Description

apig-auth-type

No

Object

Security authentication mode. This parameter is a null array.

Options:

  • apig-auth-app: App authentication
  • apig-auth-iam: IAM authentication
  • Null: No authentication required
Table 12 Parameter description of status code

Parameter

Mandatory

Type

Description

description

No

String

Response description

schema

No

Object

Response body. For details, see Table 13.

Table 13 Parameter description of schema

Parameter

Mandatory

Type

Description

description

No

String

Body description

type

No

String

Body type, which can be FORM or STREAM

Table 14 Parameter description of securityDefinitions

Parameter

Mandatory

Type

Description

name

Yes

Object

Security authentication mode. For details, see Table 15.

Table 15 Parameter description of name

Parameter

Mandatory

Type

Description

type

Yes

String

Authentication type. apiKey is supported.

name

Yes

String

Name of apiKey

in

Yes

String

Location of apiKey

x-apigateway-auth-type

Yes

String

Authentication type extended based on apiKey. Authentication types AppSigv1, IAM, and IAM_NONE are supported.

Table 16 Parameter description of x-apigateway-backend

Parameter

Mandatory

Type

Description

type

Yes

String

Backend type. The options include HTTP, HTTP-VPC, and MOCK.

parameters

No

Object

Backend parameters. For details, see Table 18.

backend_define

Yes

Object

Backend definition

The following backend definitions are supported:

Table 17 Parameter description of x-apigateway-backend-policies

Parameter

Mandatory

Type

Description

type

Yes

String

Backend type. The options include HTTP, HTTP-VPC, and MOCK.

name

Yes

String

Backend policy name

parameters

No

Object

Backend parameters. For details, see Table 18.

backend_define

Yes

Object

Backend definition

The following backend definitions are supported:

conditions

Yes

Object

Policy conditions. For details, see Table 22.

effectMode

Yes

String

Effective mode of the backend policy. The options include ANY and ALL.

Table 18 Backend parameter description

Parameter

Mandatory

Type

Description

name

Yes

String

Parameter name, which consists of a maximum of 32 bytes, starting with a letter. Only letters, digits, periods (.), hyphens (-), and underscores (_) are allowed.

The names of header parameters are not case-sensitive.

value

Yes

String

Parameter value, which is a parameter name if the parameter comes from a request

in

Yes

String

Parameter location, which can be header, query, or path

origin

Yes

String

Parameter mapping source. The options include REQUEST and CONSTANT.

description

No

String

Parameter meaning

Table 19 Parameter description of backend httpEndpoints

Parameter

Mandatory

Type

Description

address

Yes

String

Backend service address. The format is <Domain name or IP address>:[Port number]

scheme

Yes

String

Backend request protocol. HTTP and HTTPS are supported.

method

Yes

String

Backend request method. The options include GET, POST, PUT, DELETE, HEAD, OPTIONS, PATCH, and ANY.

path

Yes

String

Backend request path, which can contain variables.

timeout

No

Integer

Backend request timeout in milliseconds. The value ranges from 1 to 60,000, and the default value is 5000.

description

No

String

Backend description

Table 20 Parameter description of backend httpVpcEndpoints

Parameter

Mandatory

Type

Description

name

Yes

Array

VPC channel name

scheme

Yes

String

Backend request protocol. HTTP and HTTPS are supported.

method

Yes

String

Backend request method. The options include GET, POST, PUT, DELETE, HEAD, OPTIONS, PATCH, and ANY.

path

Yes

String

Backend request path, which can contain variables.

timeout

No

Integer

Backend request timeout in milliseconds. The value ranges from 1 to 60,000, and the default value is 5000.

host

No

String

VPC channel proxy host

description

No

String

Backend description

Table 21 Parameter description of backend mockEndpoints

Parameter

Mandatory

Type

Description

result-content

Yes

String

Mock response

description

No

String

Backend description

Table 22 Parameter description of conditions

Parameter

Mandatory

Type

Description

type

Yes

String

Policy condition type. The options include equal, enum, and pattern.

value

Yes

String

Policy condition value

origin

Yes

String

Policy condition source. The options include source and request.

parameter

No

String

Input parameter name if the origin parameter is set to request.

Table 23 Parameter description of x-apigateway-access-controls

Parameter

Mandatory

Type

Description

acl_name

No

Object

Access control policy. For details, see Table 24.

Table 24 Parameter description of acl_name

Parameter

Mandatory

Type

Description

acl-type

Yes

String

Access control effect. The options include PERMIT and DENY.

entity-type

Yes

String

Access control object. Only IP addresses and accounts are supported.

value

Yes

String

Access control values, which are separated with commas (,).

Table 25 Parameter description of x-apigateway-ratelimits

Parameter

Mandatory

Type

Description

throttle_name

No

Object

Request throttling policy. For details, see Table 26.

Table 26 Parameter description of throttle_name

Parameter

Mandatory

Type

Description

api-limit

Yes

Integer

Maximum number of times an API can be called

user-limit

No

Integer

Number of times the API can be called by a user

app-limit

No

Integer

Number of times the API can be called by an app

ip-limit

No

Integer

Number of times the API can be called by an IP address

interval

Yes

Integer

Throttling period

unit

Yes

String

Throttling unit, which can be SECOND, MINUTE, HOUR, or DAY

shared

No

Boolean

Whether to share the throttling limits among APIs

special

No

Object

Excluded request throttling configurations. For details, see Table 27.

Table 27 Parameter description of special

Parameter

Mandatory

Type

Description

type

Yes

String

Excluded request throttling type, which can be APP or USER

limit

Yes

Integer

Access limit

instance

Yes

String

Excluded app or user

Example response:

{
	"swagger": "2.0",
	"info": {
		"description": "api group test",
		"title": "APIGroup_test",
		"version": "2019-09-12-17:38:10"
	},
	"host": "6b075335476a4943bf70c3db1343c912.apigw.example.com",
	"paths": {
		"/test/{path}": {
			"get": {
				"security": [
					{
						"apig-auth-app": []
					}
				],
				"description": "api test",
				"schemes": [
					"https"
				],
				"operationId": "API_test",
				"parameters": [
					{
						"type": "string",
						"description": "header parameter",
						"name": "header",
						"in": "header",
						"required": true
					},
					{
						"type": "string",
						"description": "path parameter",
						"name": "path",
						"in": "path",
						"required": true
					},
					{
						"type": "number",
						"default": "123",
						"description": "query parameter",
						"name": "query",
						"in": "query"
					}
				],
				"responses": {
					"default": {
						"$ref": "#/responses/default"
					},
					"x-apigateway-result-failure-sample": "",
					"x-apigateway-result-normal-sample": "success"
				},
				"x-apigateway-backend": {
					"httpEndpoints": {
						"address": "1.1.1.1:443",
						"description": "",
						"method": "GET",
						"path": "/test/{path}",
						"scheme": "https",
						"timeout": 5000
					},
					"parameters": [
						{
							"description": "",
							"in": "HEADER",
							"name": "header",
							"origin": "REQUEST",
							"value": "header"
						},
						{
							"description": "",
							"in": "PATH",
							"name": "path",
							"origin": "REQUEST",
							"value": "path"
						},
						{
							"description": "",
							"in": "QUERY",
							"name": "query",
							"origin": "REQUEST",
							"value": "query"
						}
					],
					"type": "HTTP"
				},
				"x-apigateway-backend-policies": [
					{
						"conditions": [
							{
								"origin": "param",
								"parameter": "path",
								"type": "exact",
								"value": "path"
							},
							{
								"origin": "source",
								"parameter": "",
								"type": "",
								"value": "1.0.0.0/8"
							}
						],
						"effectMode": "ANY",
						"httpVpcEndpoints": {
							"method": "POST",
							"name": "VPC_n9ct",
							"path": "/",
							"scheme": "HTTPS",
							"timeout": 5000
						},
						"name": "policy_test",
						"type": "HTTP-VPC"
					}
				],
				"x-apigateway-cors": false,
				"x-apigateway-match-mode": "NORMAL",
				"x-apigateway-request-type": "public"
			}
		}
	},
	"responses": {
		"default": {
			"description": "response example"
		}
	},
	"securityDefinitions": {
		"apig-auth-app": {
			"type": "apiKey",
			"name": "Authorization",
			"in": "header",
			"x-apigateway-auth-type": "AppSigv1"
		},
		"apig-auth-iam": {
			"type": "apiKey",
			"name": "unused",
			"in": "header",
			"x-apigateway-auth-type": "IAM"
		}
	}
}

Status Codes

Table 28 Status codes

Status Code

Description

200

OK

400

bad request

401

unauthorized

403

forbidden

500

server internal error