All Products
Search
Document Center

Import Swagger files to create APIs

Last Updated: Nov 23, 2021

Swagger is a specification used to describe API definitions. It is widely used to define and describe APIs for backend services. You can call the Create APIs By Importing Swagger operation 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, see Compatibility.

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 Swagger Operation 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 to Operation Object and 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 to Operation Object and 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 to Operation Object and 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 to Operation Object and specifies the mappings between request parameters and backend service parameters. If you select PASSTHROUGH as the mapping relationship, the Parameter Object does 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 to Operation Object and 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 to Operation Object and 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 to Operation Object and 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 to Parameter Object and 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 to Parameter Object and 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 to Parameter Object and 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 to Path Item Object and 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 to Operation Object and 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.