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.

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

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:

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

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 Gateway
Parameter type in Swagger Parameter type in API Gateway Supported verification parameter and rule
  • 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 -
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 API entities based on the Swagger extensions.

Note 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-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
4.2 Description of the Definition field in Swagger

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.