Swagger is a specification used to describe API definitions, and is widely used to define and describe APIs for backend services. You can now create APIs by importing Swagger 2.0 files into API Gateway. For more information, see ImportSwagger, or operate in the console, as in the following figure:

import swagger

The API Gateway Swagger extension is based on Swagger 2.0. You can create the Swagger definition for API entities, and import the Swagger file into API Gateway for bulk creations or updating API entities. By default, API Gateway supports Swagger 2.0, which is compatible with most Swagger specifications. However, these Swagger versions have some differences. For more information, see Swagger Compatibility Reference.

This topic describes API Gateway extensions based on Swagger, and provides related examples to describe implementation.

Note: All parameters and valid values in Swagger are case-sensitive.

1. Swagger extensions:

The Swagger extensions are used to extend native Swagger Operation Object, providing features such as authentication, parameter mapping, and backend services. In addition, these extensions include the support for processing the ANY method in order to respond to requests made through any HTTP method.All extensions begin with x-aliyun-apigateway-, which are described as follows:

1.1 x-aliyun-apigateway-auth-type: authentication type

The authentication type is applied to Operation Object. The extension is used to specify the API authentication type.

Value range :

APP (Default): the application authentication for Alibaba Cloud API Gateway.
ANONYMOUS: Anonymous

Example:

...
paths:
  'path/':
    get:
      x-aliyun-apigateway-auth-type: ANONYMOUS
...

1.2 x-aliyun-apigateway-parameter-handling: API mapping relationship

The API mapping relationship applied to the Operation Object, is used to specify the mapping relationship between the request parameters and the backend service parameters. When you select PASSTHROUGH as the mapping relationship, the Parameter Objectdoes not support x-aliyun-apigateway-backend-location and x-aliyun-apigateway-backend-name properties.

Value range :

PASSTHROUGH (Default): the request parameter passthrough.
MAPPING: the request parameter mapping.

Example:

...
paths:
  'path/':
    get:
      x-aliyun-apigateway-parameter-handling: MAPPING
...

1.3 x-aliyun-apigateway-backend: backend type

The backend type applied to Operation Object. The parameter is used to specify backend service information. According to the backend service type, the specific properties are as follows:

1.3.1 Backend service type: HTTP

The HTTP backend type is used to configure the service address to achieve direct backend service access.

Property description:

Property name	Type	Description
type	string	Required. The value is HTTP.
address	string	Required. The address of the backend service.
path	string	Required. The path of the backend service. Support the path variable.
method	string	Required. The backend request method.
timeout	int	Optional. The default value is 10,000. The property value range is[500,30000]

Example:

...
x-aliyun-apigateway-backend:
  type: HTTP
  address: http://10.10.100.2:8000
  path: "/users/{userId}"
  method: GET
  timeout: 7,000
...

1.3.2 Backend service type: HTTP-VPC

The HTTP-VPC backend type is deployed when the backend service is running in the VPC network. You need to Create a VPC authorization, and then import through the VPC authorized name.

Property description:

Property name	Type	Description
type	string	Required. The value is HTTP-VPC.
vpcAccessName	string	Required. The VPC network name that is used by the backend service.
path	string	Required. Specify the backend service path. Support the path variable.
method	string	Required. The backend request method.
timeout	int	Optional. The default value is 10,000. The property value range is[500,30000]

Example:

...
x-aliyun-apigateway-backend:
  type: HTTP_VPC
  vpcAccessName: vpcAccess1
  path: "/users/{userId}"
  method: GET
  timeout: 10,000
...

1.3.3 Backend service type: FC

The FC backend type is used to configure the service address to Function Compute backend service access.

Property description:

	Property name	Type
type	string	Required；The value is FC
fcRegion	string	Required: The region that FC belongs to
serviceName	string	Required: The service name of current FC
functionName	string	Required：The function name of current FC
arn	string	Required: Arn of the current FC.

Example:

...
x-aliyun-apigateway-backend:
  type: FC
  fcRegion: cn-shanghai
  serviceName: fcService
  functionName: fcFunction
  arn: acs:ram::111111111:role/aliyunapigatewayaccessingfcrole
...

1.3.4 Backend service type: MOCK

The MOCK backend type is used to simulate the backend service call by returning the default response.

Property description:

Property name	Type	Description
type	string	Required. The value is MOCK.
mockResult	string	Required. The response result of MOCK.

Example:

...
x-aliyun-apigateway-backend:
  type: MOCK
  mockResult: mock resul sample
...

1.4 x-aliyun-apigateway-Constant-parameters: constant parameters

A constant parameter applied toOperation Object is used to specify the parameter applied to the backend service.

Property description:

Property name	Type	Description
backendName	string	Required. The backend parameter name.
value	string	Required. The constant value.
location	String	Required. The location of the constant parameter. You can specify[query,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.5 x-aliyun-apigateway-system-parameters: the backend service parameters.

A backend service parameter applied to Operation Object is used to define the system parameters of the API backend service.

Property description:

Property name	Type	Description
systemName	string	Required. The system parameter name.
backendName	string	Required. The backend parameter name.
location	String	Required. The location of the constant parameter. You can specify[query,header]

Example:

...
    x-aliyun-apigateway-system-parameters:
        - systemName: CaAppId
          backendName: appId
          location: header
   ...

1.6 x-aliyun-apigateway-backend-location: the backend parameter location.

The backend parameter location is applied Parameter Object. The property applies only when the setting is x-aliyun-apigateway-parameter-handling: MAPPING. After the parameter mapping is set, the property is used to specify the parameter location when the backend service sends a request.

Value range :

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.7 x-aliyun-apigateway-backend-name: the backend parameter name.

The backend parameter name is applied to Parameter Object. This property applies only when the setting is x-aliyun-apigateway-parameter-handling: MAPPING. After the parameter mapping is set, the property is used to specify the parameter name when the backend service sends a request.

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.8 x-aliyun-apigateway-any-method: ANY method

The ANY method is applied to Path Item Object. The method sets an API to accept any type of HTTP request.

Example:

...
paths:
  'path/':
     x-aliyun-apigateway-any-method:
     ...
...

2. Compatibility

The differences between API Gateway and the Swagger specification when defining APIs are as follows:

2.1 Comparison between Swagger parameter types and original API Gateway type

Swagger type	API Gateway type	Supported verification parameters and rules
type:integer format:int32	Int	mininum maxnum
type:integer format:int64	Long	mininum maxnum
type:number format:float	Float	mininum maxnum
type:number format:double	Doulbe	mininum maxnum
type:string	String	maxLength enumValues pattern
type:boolean format:Boolean	Boolean	-

3. Swagger example

This topic provides three examples of Swagger extensions that are based on 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.

Note: The examples are only for your reference.

3.1 Swagger example with HTTP as the API Gateway backend service

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-auth-type: ANONYMOUS
      x-aliyun-apigateway-backend:
        type: HTTP
        address: 'http://www.aliyun.com'
        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
      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'
        path: '/builtin/echo/{backend}'
        method: post
        timeout: 10000
      consumes:
        - application/x-www-form-urlencoded
      parameters:
        - name: userId
          required: true
          in: path
          type: string
          x-aliyun-apigateway-backend-name: backend
        - 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
        - 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: 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

3.2 Swagger example with HTTP-VPC as the API Gateway backend service

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 Swagger example with Function Compute as the API Gateway backend service

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 Swagger example with MOCK as the API Gateway backend service

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