Swagger is a set of specifications that is widely used to define and describe APIs for backend services. API Gateway allows you to import files based on the Swagger 2.0 specification. You can call the ImportSwagger operation or use the console to import Swagger-compliant data, as shown in the following figure.
API Gateway Swagger extensions are based on Swagger 2.0. You can create Swagger-based definitions for APIs and import Swagger files into the API Gateway console to create or update multiple APIs at a time. API Gateway supports Swagger 2.0 by default and is compatible with most Swagger specification versions. However, implementation differences exist between Swagger 2.0 and other Swagger specification versions.
This topic describes API Gateway Swagger extensions and provides examples of their implementations.
All the parameters and their values in Swagger are case-sensitive.
1. Extensions supported by Swagger
Swagger supports extensions to its native Operation Object. Extensions are used to provide features for authentication, parameter mapping, and backend service purposes. In addition, the x-aliyun-apigateway-any-method extension is used to specify the HTTP method that API callers can use to call APIs. All extensions related to API Gateway start with x-aliyun-apigateway-
. The following sections describe the extensions.
1.1 x-aliyun-apigateway-auth-type: authorization type
Applies to Operation Object and specifies an API authorization type.
Valid values:
APP (default): An Alibaba Cloud application must be used as the identity to call an API.
ANONYMOUS: Any user can call an API without using an application as the identity.
Example:
...
paths:
'path/':
get:
x-aliyun-apigateway-auth-type: ANONYMOUS
...
1.2 x-aliyun-apigateway-api-market-enable: publishing to Alibaba Cloud Marketplace
Applies to Operation Object and specifies whether an API is published to Alibaba Cloud Marketplace.
Valid values:
true
false (default)
Example:
...
paths:
'path/':
get:
x-aliyun-apigateway-api-market-enable: true
...
1.3 x-aliyun-apigateway-api-force-nonce-check: forcible nonce verification
Applies to Operation Object and specifies whether to perform forcible nonce verification on an API.
Valid values:
true
false (default)
Example:
...
paths:
'path/':
get:
x-aliyun-apigateway-api-force-nonce-check: true
...
1.4 x-aliyun-apigateway-parameter-handling: API mapping
Applies to Operation Object and specifies the mappings between request parameters and backend service parameters. If you select PASSTHROUGH, Parameter Object does not support x-aliyun-apigateway-backend-location
and x-aliyun-apigateway-backend-name
.
Valid values:
PASSTHROUGH (default): Request parameters are passed to the backend service without mapping.
MAPPING: Request parameters are mapped to backend service parameters.
Example:
...
paths:
'path/':
get:
x-aliyun-apigateway-parameter-handling: MAPPING
...
1.5 x-aliyun-apigateway-backend: backend service type
Applies to Operation Object and specifies the backend service type. Specific properties vary based on the backend service type. For details, see the following tables.
1.5.1 HTTP
This type is used in scenarios in which the backend service can be directly accessed. You can directly configure a URL for backend services of this type.
Property description:
Property | Type | Description |
type | string | Required. The value is HTTP. |
address | string | Required. The URL 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. Valid values: 500 to 30000. |
Example:
...
x-aliyun-apigateway-backend:
type: HTTP
address: 'http://www.aliyun.com'
path: '/builtin/echo'
method: get
timeout: 10000
...
1.5.2 HTTP-VPC
If a backend service is running on a virtual private cloud (VPC), this type is used. To configure the backend service, you must first create a VPC access authorization. For more information, see the topic that describes how to create an API with a resource in a VPC as the backend service.
Property description:
Property | Type | Description |
type | string | Required. The value is HTTP-VPC. |
vpcAccessName | string | Required. The name of the VPC access authorization that is used to access 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. Valid values: 500 to 30000. |
Example:
...
x-aliyun-apigateway-backend:
type: HTTP_VPC
vpcAccessName: vpcAccess1
path: '/users/{userId}'
method: GET
timeout: 10000
...
1.5.3 FC
If the backend service is Function Compute, you must set the backend service type to FC.
Property description:
Property | Type | Description |
type | string | Required. The value is FC. |
fcRegion | string | Required. The region where your Function Compute service and function are deployed. |
serviceName | string | Required. The name of the service in Function Compute. |
functionName | string | Required. The name of the function in Function Compute. |
arn | string | Optional. The Resource Access Management (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 MOCK
This type is used to simulate expected return results.
Property description:
Property | Type | Description |
type | string | Required. The value is MOCK. |
mockResult | string | Required. The mocked results. |
mockStatusCode | Integer | Optional. |
mockHeaders | Header | Optional. |
Header description:
Property | 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 to Operation Object and defines the constant parameters that are always received by the backend service. You do not need to include these parameters in the requests that are sent to the backend service.
Property description:
Property | Type | Description |
backendName | string | Required. The name of the constant parameter. |
value | string | Required. The value of the constant parameter. |
location | String | Required. The location of the constant parameter. 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 the backend service
Applies to Operation Object and specifies the system parameters of the backend service.
Property description:
Property | Type | Description |
systemName | string | Required. The name of the system parameter. |
backendName | string | Required. The mapped name of the system parameter in the backend service. |
location | String | Required. The location of the system parameter. 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 locations
Applies to Parameter Object and specifies the mapped locations of request parameters in the 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 names
Applies to Parameter Object and specifies the mapped names of request parameters in the 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: schema definitions for query parameters
Applies to Parameter Object and defines a schema for a query parameter. 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 to Path Item Object and specifies the HTTP method that can be used to make call APIs.
Example:
...
paths:
'path/':
x-aliyun-apigateway-any-method:
...
...
1.12 x-aliyun-apigateway-app-code-type: AppCode-based simple authentication
Applies to Operation Object and specifies whether an API supports AppCode-based simple authentication.
Valid values:
DEFAULT (default): AppCode-based simple authentication is enabled.
DISABLE: AppCode-based simple authentication is disabled.
HEADER: An AppCode is carried as a header in a request.
HEADER_QUERY: An AppCode is carried as a header or a Query parameter in a request.
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 Parameter types
Parameter type in Swagger | Parameter type in API Gateway | Supported verification parameter and rule |
| Int |
|
| Long |
|
| Float |
|
| Double |
|
| String |
|
| Boolean | - |
2.2 Support for the consumes field
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 APIs based on the Swagger extensions.
The examples are for reference only.
3.1 Example with HTTP as the backend service type
swagger: '2.0'
basePath: /
info:
version: '0.9'
title: Aliyun Api Gateway Swagger Sample
schemes:
- http
- https
x-aliyun-apigateway-parameter-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 FC 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 Scope of extensions
Some extensions use the global values if the extensions are not specified for a specific API. If a different value is individually specified for a specific API, the individually specified value takes effect. The following items list those extensions.
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
4.2 Description of the Definition field in Swagger
API Gateway supports model definition in Swagger importing. However, the model definition differs from that in Swagger specifications. Model definition is used to generate SDKs. The following limits are imposed on top of 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.