Swaggeris a specification used to describe API definitions. It is widely used to define and describe APIs for backend services. You can call theCreate APIs By Importing Swaggeroperation to import Swagger 2.0 files for the creation of APIs. You can also import Swagger 2.0 files in the API Gateway console, as shown in the following figure.

API Gateway Swagger extensions are based on Swagger 2.0. You can create a Swagger definition for API entities and import Swagger files into the API Gateway console to create or update API entities. API Gateway supports Swagger 2.0 by default, which is compatible with most Swagger specifications. However, there are some differences in specification compliance for API creation. For more information, seeCompatibility.
This topic describes API Gateway Swagger extensions and provides examples of their implementations.
1. Swagger extensions
Swagger extensions are used to extend the native SwaggerOperation Object.They provide features such as authentication, parameter mapping, and backend services.
The x-aliyun-apigateway-any-method extension is added. It is used to specify the HTTP
method, by using which you can call APIs. All extensions start with x-aliyun-apigateway-
, which are described as follows:
Applies toOperation Objectand specifies an API authorization type.
Valid values:
- APP: app authorization for Alibaba Cloud API Gateway. This is the default value.
- ANONYMOUS: anonymous authorization.
Example:
...
paths:
'path/':
get:
x-aliyun-apigateway-auth-type: ANONYMOUS
...
1.2 x-aliyun-apigateway-api-market-enable: publishing to the Alibaba Cloud Marketplace
Applies toOperation Objectand specifies whether an API is published to the Alibaba Cloud Marketplace.
Valid values:
- true
- false: This is the default value.
Example:
...
paths:
'path/':
get:
x-aliyun-apigateway-api-market-enable: true
...
1.3 x-aliyun-apigateway-api-force-nonce-check: forcible nonce verification
Applies toOperation Objectand specifies whether to perform forcible nonce verification on an API.
Valid values:
- true
- false: This is the default value.
Example:
...
paths:
'path/':
get:
x-aliyun-apigateway-api-force-nonce-check: true
...
1.4 x-aliyun-apigateway-parameter-handling: API mapping relationship
Applies toOperation Objectand specifies the mappings between request parameters and backend service parameters.
If you select PASSTHROUGH as the mapping relationship, theParameter Objectdoes not support x-aliyun-apigateway-backend-location
and x-aliyun-apigateway-backend-name
.
Valid values:
- PASSTHROUGH: request parameter passthrough. This is the default value.
- MAPPING: request parameter mapping.
Example:
...
paths:
'path/':
get:
x-aliyun-apigateway-parameter-handling: MAPPING
...
1.5 x-aliyun-apigateway-backend: backend service type
Applies toOperation Objectand specifies backend service information. Specific properties vary based on the backend service type. For details, see the following tables.
1.5.1 Backend service type: HTTP
This type is used to configure backend service addresses. If backend service addresses can be directly accessed, this type is used.
Property description
Property name | Type | Description |
---|---|---|
type | string | Required. The value is HTTP. |
address | string | Required. The address of the backend service. |
path | string | Optional. The path of the backend service. The value can be a variable. By default, the value of this property is the same as the root path. |
method | string | Required. The backend request method. |
timeout | int | Optional. The default value is 10000. Value range: [500,30000]. |
Example:
...
x-aliyun-apigateway-backend:
type: HTTP
address: 'http://www.aliyun.com'
path: '/builtin/echo'
method: get
timeout: 10000
...
1.5.2 Backend service type: HTTP-VPC
If a backend service is running on a VPC, this type is used. To configure the backend service, you need to Create an API operation with a resource in a VPC as the backend service and use the VPC authorization name.
Property description
Property name | Type | Description |
---|---|---|
type | string | Required. The value is HTTP-VPC. |
vpcAccessName | string | Required. The name of the VPC on which the backend service is running. |
path | string | Optional. The path of the backend service. The value can be a variable. By default, the value of this property is the same as the root path. |
method | string | Required. The backend request method. |
timeout | int | Optional. The default value is 10000. Value range: [500,30000]. |
Example:
...
x-aliyun-apigateway-backend:
type: HTTP_VPC
vpcAccessName: vpcAccess1
path: '/users/{userId}'
method: GET
timeout: 10000
...
1.5.3 Backend service type: FC
The backend service type is Function Compute.
Property description
Property name | Type | Description |
---|---|---|
type | string | Required. The value is FC. |
fcRegion | string | Required. The region where Function Compute is deployed. |
serviceName | string | Required. The service name of Function Compute. |
functionName | string | Required. The function name of Function Compute. |
arn | string | Optional. RAM authorization for Function Compute. |
Example:
...
x-aliyun-apigateway-backend:
type: FC
fcRegion: cn-shanghai
serviceName: fcService
functionName: fcFunction
arn: acs:ram::111111111:role/aliyunapigatewayaccessingfcrole
...
1.5.4 Backend service type: MOCK
This type is used to simulate expected return results.
Property description
Property name | Type | Description |
---|---|---|
type | string | Required. The value is MOCK. |
mockResult | string | Required. Return results simulated by Mock. |
mockStatusCode | Integer | Optional. |
mockHeaders | Header | Optional. |
Header description
Property name | Type | Description |
---|---|---|
name | string | Required. |
value | string | Required. |
Example:
...
x-aliyun-apigateway-backend:
type: MOCK
mockResult: mock resul sample
mockStatusCode: 200
mockHeaders:
- name: server
value: mock
- name: proxy
value: GW
...
1.6 x-aliyun-apigateway-constant-parameters: constant parameters
Applies toOperation Objectand defines the constant parameters that are always received by backend services. However, you do not need to include these parameters in the requests that are sent to the backend services.
Property description
Property name | Type | Description |
---|---|---|
backendName | string | Required. The name of the constant parameter that is always received by the backend service. |
value | string | Required. The value of the constant parameter. |
location | String | Required. The location in which the constant parameter is carried. Valid values: query and header. |
description | string | Optional. The description of the constant parameter. |
Example:
...
x-aliyun-apigateway-constant-parameters:
- backendName: swaggerConstant
value: swaggerConstant
location: header
description: description of swagger
...
1.7 x-aliyun-apigateway-system-parameters: system parameters of backend services
Applies toOperation Objectand specifies the system parameters of backend services.
Property description
Property name | Type | Description |
---|---|---|
systemName | string | Required. The name of the system parameter. |
backendName | string | Required. The name of the backend parameter. |
location | String | Required. The location in which the system parameter is carried. Valid values: query and header. |
Example:
...
x-aliyun-apigateway-system-parameters:
- systemName: CaAppId
backendName: appId
location: header
...
1.8 x-aliyun-apigateway-backend-location: backend parameter location
Applies toParameter Objectand specifies the location in which a parameter is carried in a request sent to a
backend service. This extension takes effects only when x-aliyun-apigateway-parameter-handling
is set to MAPPING.
Valid values:
- path
- header
- query
- formData
Example:
...
parameters:
- name: swaggerHeader
in: header
required: false
type: number
format: double
minimum: 0.1
maximum: 0.5
x-aliyun-apigateway-backend-location: query
x-aliyun-apigateway-backend-name: backendQuery
...
1.9 x-aliyun-apigateway-backend-name: backend parameter name
Applies toParameter Objectand specifies the name of a parameter in a request sent to a backend service. This
extension takes effects only when x-aliyun-apigateway-parameter-handling
is set to MAPPING.
Example:
...
parameters:
- name: swaggerHeader
in: header
required: false
type: number
format: double
minimum: 0.1
maximum: 0.5
x-aliyun-apigateway-backend-location: query
x-aliyun-apigateway-backend-name: backendQuery
...
1.10 x-aliyun-apigateway-query-schema: model definition for query parameters
Applies toParameter Objectand defines a model for query parameters. This extension can be used when a parameter is of the STRING type and is defined as a query parameter.
Example:
...
parameters:
- name: event_info
in: query
required: true
type: string
x-aliyun-apigateway-query-schema:
$ref: "#/definitions/EvnetInfo"
...
1.11 x-aliyun-apigateway-any-method: ANY method
Applies toPath Item Objectand specifies the HTTP method, by using which you can call APIs.
Example:
...
paths:
'path/':
x-aliyun-apigateway-any-method:
...
...
1.12 x-aliyun-apigateway-app-code-type: AppCode-based simple authentication
Applies toOperation Objectand specifies whether an API supports AppCode-based simple authentication.
Valid values:
- DEFAULT: AppCode-based simple authentication is supported by default.
- DISABLE: AppCode-based simple authentication is disabled.
- HEADER: AppCode is carried in the header of a request.
- HEADER_QUERY: AppCode is carried in the header of a request or in a query parameter.
Example:
...
paths:
'path/':
get:
x-aliyun-apigateway-app-code-type: HEADER
...
2. Compatibility
API Gateway and Swagger specifications define APIs in different ways.
2.1 Comparison of the parameter types in Swagger and API GatewayParameter type in Swagger | Parameter type in API Gateway | Supported verification parameter and rule |
---|---|---|
|
Int |
|
|
Long |
|
|
Float |
|
|
Doulbe |
|
type:string | String |
|
|
Boolean | - |
If a Swagger configuration file contains FormData parameters, the consumes field must
be configured. In API Gateway, this field can only be set to application/x-www-form-urlencoded
.
consumes:
- application/x-www-form-urlencoded
3. Swagger extension examples
This section provides four examples of Swagger extensions for API Gateway. The examples cover practically all aspects of the Swagger extensions. You can refer to these examples when you define API entities based on the Swagger extensions.
swagger: '2.0'
basePath: /
info:
version: '0.9'
title: Aliyun Api Gateway Swagger Sample
schemes:
- http
- https
x-aliyun-apigateway-paramater-handling: MAPPING
x-aliyun-apigateway-api-market-enable: true
x-aliyun-apigateway-api-force-nonce-check: true
x-aliyun-apigateway-backend:
type: HTTP
address: 'http://www.aliyun.com'
method: get
timeout: 10000
paths:
'/http/get/mapping/{userId}':
get:
operationId: case1
schemes:
- http
- https
x-aliyun-apigateway-parameter-handling: MAPPING
x-aliyun-apigateway-api-market-enable: true
x-aliyun-apigateway-auth-type: ANONYMOUS
parameters:
- name: userId
in: path
required: true
type: string
- name: swaggerQuery
in: query
required: false
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-aliyun-apigateway-backend-location: query
x-aliyun-apigateway-backend-name: backendQuery
x-aliyun-apigateway-constant-parameters:
- backendName: swaggerConstant
value: swaggerConstant
location: header
description: description of swagger
x-aliyun-apigateway-system-parameters:
- systemName: CaAppId
backendName: appId
location: header
responses:
'200':
description: 200 description
'400':
description: 400 description
'/echo/test/post/{userId}':
post:
operationId: testpost
schemes:
- http
- https
x-aliyun-apigateway-parameter-handling: MAPPING
x-aliyun-apigateway-backend:
type: HTTP
address: 'http://www.aliyun.com'
method: post
timeout: 10000
consumes:
- application/x-www-form-urlencoded
parameters:
- name: userId
required: true
in: path
type: string
- name: swaggerQuery1
in: query
required: false
default: '123465'
type: integer
format: int32
minimum: 0
maximum: 100
x-aliyun-apigateway-enum: 1,2,3
- name: swaggerQuery2
in: query
required: false
type: string
x-aliyun-apigateway-backend-location: header
x-aliyun-apigateway-backend-name: backendHeader
x-aliyun-apigateway-query-schema:
$ref: '#/definitions/AiGeneratePicQueryVO'
- name: swaggerHeader
in: header
required: false
type: number
format: double
minimum: 0.1
maximum: 0.5
x-aliyun-apigateway-backend-location: query
x-aliyun-apigateway-backend-name: backendQuery
- name: swaggerFormdata
in: formData
required: true
type: string
responses:
'200':
description: 200 description
schema:
$ref: '#/definitions/ResultOfGeneratePicturesVO'
'400':
description: 400 description
x-aliyun-apigateway-any-method:
operationId: case2
schemes:
- http
- https
x-aliyun-apigateway-parameter-handling: MAPPING
x-aliyun-apigateway-backend:
type: HTTP
address: 'http://www.aliyun.com'
path: '/builtin/echo/{abc}'
method: post
timeout: 10000
parameters:
- name: userId
in: path
required: false
default: '123465'
type: integer
format: int32
minimum: 0
maximum: 100
x-aliyun-apigateway-backend-name: abc
x-aliyun-apigateway-backend-location: path
responses:
'200':
description: 200 description
'400':
description: 400 description
definitions:
AiGeneratePicQueryVO:
type: object
properties:
transactionId:
type: string
description: asynchronous task ID
GeneratePictureVO:
type: object
properties:
id:
type: integer
format: int64
description: image ID
name:
type: string
description: image name
GeneratePicturesVO:
type: object
properties:
failSize:
type: integer
format: int64
description: number of failures
list:
type: array
description: image list
items:
$ref: '#/definitions/GeneratePictureVO'
title: GeneratePictureVO
successSize:
type: integer
format: int32
description: number of successes
totalSize:
type: number
format: float
description: total number of requests
ResultOfGeneratePicturesVO:
type: object
properties:
model:
description: returned content
$ref: '#/definitions/GeneratePicturesVO'
title: GeneratePicturesVO
requestId:
type: string
description: request ID
3.2 Example with HTTP-VPC as the backend service type
swagger: '2.0'
basePath: /
info:
version: '0.9'
title: Aliyun Api Gateway Swagger Sample
schemes:
- http
- https
paths:
'/http/get/mapping/{userId}':
get:
operationId: case1
schemes:
- http
- https
x-aliyun-apigateway-parameter-handling: MAPPING
x-aliyun-apigateway-backend:
type: HTTP-VPC
vpcAccessName: vpcName1
path: '/builtin/echo/{userId}'
method: get
timeout: 10000
parameters:
- name: userId
in: path
required: true
type: string
- name: swaggerQuery
in: query
required: false
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-aliyun-apigateway-backend-location: query
x-aliyun-apigateway-backend-name: backendQuery
responses:
'200':
description: 200 description
'400':
description: 400 description
'/echo/test/post':
post:
operationId: testpost
schemes:
- http
- https
x-aliyun-apigateway-parameter-handling: MAPPING
x-aliyun-apigateway-backend:
type: HTTP-VPC
vpcAccessName: vpcName2
path: '/builtin/echo'
method: post
timeout: 10000
consumes:
- application/x-www-form-urlencoded
parameters:
- name: swaggerQuery1
in: query
required: false
default: '123465'
type: integer
format: int32
minimum: 0
maximum: 100
- name: swaggerQuery2
in: query
required: false
type: string
x-aliyun-apigateway-backend-location: header
x-aliyun-apigateway-backend-name: backendHeader
- name: swaggerHeader
in: header
required: false
type: number
format: double
minimum: 0.1
maximum: 0.5
x-aliyun-apigateway-backend-location: query
x-aliyun-apigateway-backend-name: backendQuery
- name: swaggerFormdata
in: formData
required: true
type: string
responses:
'200':
description: 200 description
'400':
description: 400 description
x-aliyun-apigateway-any-method:
operationId: case2
schemes:
- http
- https
x-aliyun-apigateway-parameter-handling: PASSTHROUGH
x-aliyun-apigateway-backend:
type: HTTP-VPC
vpcAccessName: vpcName3
path: '/builtin/echo'
method: post
timeout: 10000
responses:
'200':
description: 200 description
'400':
description: 400 description
3.3 Example with Function Compute as the backend service type
swagger: '2.0'
basePath: /
info:
version: '0.9'
title: Aliyun Api Gateway Swagger Sample
schemes:
- http
- https
paths:
'/http/get/mapping/{userId}':
get:
operationId: case1
schemes:
- http
- https
x-aliyun-apigateway-parameter-handling: MAPPING
x-aliyun-apigateway-backend:
type: FC
fcRegion: cn-shanghai
serviceName: fcService
functionName: fcFunction
arn: acs:ram::111111111:role/aliyunapigatewayaccessingfcrole
parameters:
- name: userId
in: path
required: true
type: string
responses:
'200':
description: 200 description
'400':
description: 400 description
3.4 Example with Mock as the backend service type
swagger: '2.0'
basePath: /
info:
version: '0.9'
title: Aliyun Api Gateway Swagger Sample
schemes:
- http
paths:
'/mock/get/mapping/{userId}':
get:
operationId: case1
schemes:
- http
- https
x-aliyun-apigateway-parameter-handling: MAPPING
x-aliyun-apigateway-backend:
type: MOCK
mockResult: mock resul sample
mockStatusCode: 200
mockHeaders:
- name: server
value: mock
- name: proxy
value: GW
parameters:
- name: userId
in: path
required: true
type: string
responses:
'200':
description: 200 description
'400':
description: 400 description
4. Usage notes
Pay attention to the following instructions, which may affect Swagger importing.
4.1 Support for global scope- x-aliyun-apigateway-backend
- x-aliyun-apigateway-api-market-enable
- x-aliyun-apigateway-api-force-nonce-check
- x-aliyun-apigateway-parameter-handling
- x-aliyun-apigateway-auth-type
Swagger importing supports model definition, which differs from that in the original Swagger specifications. Model definition is used to generate SDKs. The following limits are added to the original Swagger specifications:
- The schema tag only supports the $ref type.
- The model in the Definition field only supports model definition of the object type.
- An array is defined in the model of the Definition field. If $ref is used for a reference, the title tag is required. If an array type is specified, an array list is also generated during the generation of SDKs.