Create an API by importing Swagger-API Gateway(API Gateway)-阿里云帮助中心

The Swagger extensions of API Gateway are based on Swagger 2.0. Use these extensions to write Swagger definitions for your APIs, and then import the Swagger file into API Gateway to create or update APIs in batches. API Gateway is preconfigured for Swagger 2.0 and supports most of the Swagger specification, but some differences exist.

Swagger import methods

Swagger is a specification for describing API definitions. It is widely used to define and describe the APIs of backend application services. API Gateway supports importing a Swagger 2.0 file to create APIs. You can call the ImportSwagger operation or perform the operation in the console.

In the left-side navigation pane of the API Gateway console, choose API Management > API List. Then, click Import Swagger in the upper-right corner of the page.

The following sections describe the API Gateway extensions to Swagger and provide examples that show how to use the extensions.

Important

All parameters and values in Swagger are case-sensitive.

Swagger extensions

The Swagger extensions of API Gateway mainly extend the native Operation Object of Swagger to add authentication, parameter mapping, and backend service capabilities. An extension for the ANY method is also provided to capture HTTP requests that use any method. All extensions start with x-aliyun-apigateway-. The following sections describe each extension.

Support for global scope

The following extensions support definitions at the global scope. If an extension is not defined in its own scope, the value that is defined at the global scope is automatically applied. If the extension is defined in its own scope, the value in that scope takes precedence.

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

`x-aliyun-apigateway-auth-type`: Authorization type

x-aliyun-apigateway-auth-type applies to the Operation Object and specifies the authorization type of the API.

Valid values:

APP (default): app authorization by Alibaba Cloud API Gateway.
ANONYMOUS: anonymous access.
Example:

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

`x-aliyun-apigateway-api-market-enable`: Alibaba Cloud Marketplace support

x-aliyun-apigateway-api-market-enable applies to the Operation Object and specifies whether the API can be published to Alibaba Cloud Marketplace.

Valid values:

true
false (default)
Example:

...
paths:
  'path/':
    get:
      x-aliyun-apigateway-api-market-enable: true
...

`x-aliyun-apigateway-api-force-nonce-check`: NONCE check

x-aliyun-apigateway-api-force-nonce-check applies to the Operation Object and specifies whether to enforce a NONCE check for the API.

Valid values:

true
false (default)
Example:

...
paths:
  'path/':
    get:
      x-aliyun-apigateway-api-force-nonce-check: true
...

`x-aliyun-apigateway-parameter-handling`: Parameter mapping

x-aliyun-apigateway-parameter-handling applies to the Operation Object and specifies how request parameters map to backend service parameters. If the mapping relationship is set to PASSTHROUGH, the Parameter Object does not support the x-aliyun-apigateway-backend-location and x-aliyun-apigateway-backend-name properties.

Valid values:

PASSTHROUGH (default): passes request parameters through.
MAPPING: maps request parameters.
Example:

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

`x-aliyun-apigateway-backend`: Backend service type

x-aliyun-apigateway-backend applies to the Operation Object and configures the information about the backend service. The available properties depend on the backend service type, as described in the following sections.

Backend service type: HTTP

Use the HTTP backend service type to configure the address of the backend service directly. This type is generally used when the backend address is directly accessible.

The following table describes the properties of the HTTP backend service type.

Property	Type	Description
type	string	Required. The value is `HTTP`.
address	string	Required. Identifies the address of the backend service.
path	string	Optional. Identifies the path of the backend service. Path variables are supported. By default, this value is the same as the root path.
method	string	Required. The backend request method.
timeout	int	Optional. Default value: 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
...

Backend service type: HTTP-VPC

Use the HTTP-VPC backend service type when the backend service resides in a VPC. You must first create a VPC authorization, and then import the authorization by its name. For more information, see Create an API that uses a resource in a VPC as the backend service.

The following table describes the properties of the HTTP-VPC backend service type.

Property	Type	Description
type	string	Required. The value is `HTTP-VPC`.
vpcAccessName	string	Required. The name of the VPC-connected instance that the backend service uses.
path	string	Optional. Identifies the path of the backend service. Path variables are supported. By default, this value is the same as the root path.
method	string	Required. The backend request method.
timeout	int	Optional. Default value: 10000. Valid values: 500 to 30000.

Example:

...
x-aliyun-apigateway-backend:
  type: HTTP-VPC
  vpcAccessName: vpcAccess1
  path: '/users/{userId}'
  method: GET
  timeout: 10000
...

Backend service type: FC

Use the FC backend service type when the backend service of API Gateway is Function Compute.

The following table describes the properties of the FC backend service type.

Property	Type	Description
type	string	Required. The value is `FC`.
fcRegion	string	Required. The region in which Function Compute resides.
serviceName	string	Required. The name of the Function Compute service.
functionName	string	Required. The name of the Function Compute function.
arn	string	Optional. The 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
...

Backend service type: MOCK

Use the MOCK backend service type to simulate the response that you predefine.

The following table describes the properties of the MOCK backend service type.

Property	Type	Description
type	string	Required. The value is `MOCK`.
mockResult	string	Required. The mocked response.
mockStatusCode	integer	Optional.
mockHeaders	Header	Optional.

The following table describes the properties of the Header type.

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
...

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

x-aliyun-apigateway-constant-parameters applies to the Operation Object and defines the constant parameters of the backend service.

The following table describes the properties of a constant parameter.

Property	Type	Description
backendName	string	Required. The name of the backend parameter.
value	string	Required. The constant value.
location	string	Required. The location in which the constant parameter is stored. Valid values: `query` and `header`.
description	string	Optional. Describes the constant.

Example:

...
x-aliyun-apigateway-constant-parameters:
  - backendName: swaggerConstant
    value: swaggerConstant
    location: header
    description: description of swagger
...

`x-aliyun-apigateway-system-parameters`: Backend system parameters

x-aliyun-apigateway-system-parameters applies to the Operation Object and defines the system parameters of the backend service of the API.

The following table describes the properties of a backend system parameter.

Property	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 constant parameter is stored. Valid values: `query` and `header`.

Example:

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

`x-aliyun-apigateway-backend-location`: Backend parameter location

x-aliyun-apigateway-backend-location applies to the Parameter Object and specifies the location of the parameter in the backend service request after parameter mapping. This property takes effect only when x-aliyun-apigateway-parameter-handling: MAPPING is set.

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
...

`x-aliyun-apigateway-backend-name`: Backend parameter name

x-aliyun-apigateway-backend-name applies to the Parameter Object and specifies the name of the parameter in the backend service request after parameter mapping. This property takes effect only when x-aliyun-apigateway-parameter-handling: MAPPING is set.

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
...

`x-aliyun-apigateway-query-schema`: Query parameter schema

x-aliyun-apigateway-query-schema applies to the Parameter Object and defines a model for a query parameter. You can use this extension 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"
...

`x-aliyun-apigateway-any-method`: ANY method

x-aliyun-apigateway-any-method applies to the Path Item Object and allows the API to accept HTTP requests of any type.

Example:

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

`x-aliyun-apigateway-app-code-type`: AppCode authentication

x-aliyun-apigateway-app-code-type applies to the Operation Object and specifies whether the API supports AppCode authentication.

Valid values:

DEFAULT (default)
DISABLE: disables AppCode authentication.
HEADER: passes the AppCode in a request header.
HEADER_QUERY: passes the AppCode in a request header or a query parameter.
Example:

...
paths:
  'path/':
    get:
      x-aliyun-apigateway-app-code-type: HEADER
...

Differences from the Swagger specification

API Gateway and the Swagger specification differ in the following ways when they define APIs. These differences directly affect how you use the Swagger import feature.

Mapping between Swagger parameter types and the original API Gateway types

Swagger type	API Gateway type	Supported validation parameters and rules
`type: integer`, `format: int32`	Int	`minimum`, `maximum`
`type: integer`, `format: int64`	Long	`minimum`, `maximum`
`type: number`, `format: float`	Float	`minimum`, `maximum`
`type: number`, `format: double`	Double	`minimum`, `maximum`
`type: string`	String	`maxLength`, `enumValues`, `pattern`
`type: boolean`, `format: boolean`	Boolean	-

Support for the consumes field

If a Swagger configuration file contains formData parameters, you must configure the consumes node. API Gateway currently supports only the application/x-www-form-urlencoded type.

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

Restrictions on Swagger definitions

Swagger import supports model definitions, but the implementation differs from the original Swagger specification. Model definitions are mainly used to generate software development kits (SDKs). Therefore, the following restrictions are added on top of the original Swagger specification:

The schema tag in Swagger supports only the $ref type.
A model in the Swagger definitions section supports only model definitions of the object type.
If a model in the Swagger definitions section contains an array definition, the $ref reference must be used together with the title tag. By default, an array type is generated as an ArrayList during SDK generation.

Swagger examples

The following examples are complete Swagger definitions that use the Swagger extensions of API Gateway. Use them as a starting point when you define your own APIs.

Note

The examples are for reference only.

Swagger example: HTTP backend service

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: response content
        $ref: '#/definitions/GeneratePicturesVO'
        title: GeneratePicturesVO
      requestId:
        type: string
        description: request ID

Swagger example: HTTP-VPC 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

Swagger example: Function Compute 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

Swagger example: MOCK 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

Swagger import methods

Swagger extensions

Support for global scope

x-aliyun-apigateway-auth-type: Authorization type

x-aliyun-apigateway-api-market-enable: Alibaba Cloud Marketplace support

x-aliyun-apigateway-api-force-nonce-check: NONCE check

x-aliyun-apigateway-parameter-handling: Parameter mapping

x-aliyun-apigateway-backend: Backend service type

Backend service type: HTTP

Backend service type: HTTP-VPC

Backend service type: FC

Backend service type: MOCK

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

x-aliyun-apigateway-system-parameters: Backend system parameters

x-aliyun-apigateway-backend-location: Backend parameter location

x-aliyun-apigateway-backend-name: Backend parameter name

x-aliyun-apigateway-query-schema: Query parameter schema

x-aliyun-apigateway-any-method: ANY method

x-aliyun-apigateway-app-code-type: AppCode authentication

Differences from the Swagger specification

Mapping between Swagger parameter types and the original API Gateway types

Support for the consumes field

Restrictions on Swagger definitions

Swagger examples

Swagger example: HTTP backend service

Swagger example: HTTP-VPC backend service

Swagger example: Function Compute backend service

Swagger example: MOCK backend service

`x-aliyun-apigateway-auth-type`: Authorization type

`x-aliyun-apigateway-api-market-enable`: Alibaba Cloud Marketplace support

`x-aliyun-apigateway-api-force-nonce-check`: NONCE check

`x-aliyun-apigateway-parameter-handling`: Parameter mapping

`x-aliyun-apigateway-backend`: Backend service type

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

`x-aliyun-apigateway-system-parameters`: Backend system parameters

`x-aliyun-apigateway-backend-location`: Backend parameter location

`x-aliyun-apigateway-backend-name`: Backend parameter name

`x-aliyun-apigateway-query-schema`: Query parameter schema

`x-aliyun-apigateway-any-method`: ANY method

`x-aliyun-apigateway-app-code-type`: AppCode authentication