Import Swagger files to create APIs with API Gateway extensions - API Gateway

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.

Note

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

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