Documentation
Home Page API Gateway API Gateway User Guide Create API Import and export API definitions API Gateway Swagger extensions

API Gateway Swagger extensions

Updated at:
Copy as MD
Product

API Gateway extends the Swagger 2.0 specification with custom extensions for authentication, parameter mapping, and backend service configuration. Import Swagger files to create or update APIs in bulk.

Swagger is a specification widely used to define and describe backend service APIs. API Gateway supports importing Swagger 2.0 files through the ImportSwagger operation or the console, as shown in the following figure.

image

API Gateway Swagger extensions are based on Swagger 2.0. You can define APIs using Swagger and import the files to create or update multiple APIs at a time. API Gateway is compatible with most Swagger versions, though implementation differences exist between Swagger 2.0 and other versions.

The sections below cover each extension, compatibility notes, and examples.

Note

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

1. Supported Swagger extensions

Swagger supports extensions to its native Operation Object. Extensions are used to configure authentication, parameter mapping, and backend services. All extensions start with x-aliyun-apigateway-.

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. When set to PASSTHROUGH, Parameter Object does not support x-aliyun-apigateway-backend-location or 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. Properties vary by backend service type.

1.5.1 HTTP

This type is used when the backend service is directly accessible by URL.

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 the backend service runs in a VPC, use this type. You must first create a VPC access authorization.

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, set the 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 simulates 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 constant parameters that the backend service always receives. These parameters do not need to be included in requests.

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. Takes effect 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. Takes effect 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 STRING-type 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 used to 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

  • 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

Double

  • mininum

  • maxnum

  • type:string

String

  • maxLength

  • enumValues

  • pattern

  • type:boolean

  • format:Boolean

Boolean

-

2.2 Support for the consumes field

If a Swagger file contains formData parameters, the consumes field is required. In API Gateway, this field only supports application/x-www-form-urlencoded.

consumes:
  - application/x-www-form-urlencoded

3. Swagger extension examples

The following examples cover the main Swagger extension scenarios for API Gateway.

Note

These 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

The following notes may affect Swagger importing.

4.1 Scope of extensions

Some extensions use global values unless a per-API value is specified. The per-API value takes precedence. These extensions support 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

API Gateway supports model definition in Swagger importing, but the model definition differs from the Swagger specification. Model definitions are used for SDK generation. The following limits apply:

  • The schema tag only supports the $ref type.

  • The model in the Definition field only supports model definition of the object type.

  • When an array in the Definition model uses $ref for a reference, the title tag is required. When an array type is specified, an array list is also generated during SDK generation.

Previous：Export APIs based on OASNext：Parameter mapping and verification rules