All Products
Search
Document Center

Create APIs by Importing Swagger

Last Updated: Oct 16, 2018

Swagger is a specification used to describe API definitions, and is widely used to define and describe APIs for backend services. You can now create APIs by importing Swagger 2.0 files into API Gateway. For more information, see ImportSwagger, or operate in the console, as in the following figure:

import swagger

The API Gateway Swagger extension is based on Swagger 2.0. You can create the Swagger definition for API entities, and import the Swagger file into API Gateway for bulk creations or updating API entities. By default, API Gateway supports Swagger 2.0, which is compatible with most Swagger specifications. However, these Swagger versions have some differences. For more information, see Swagger Compatibility Reference.

This topic describes API Gateway extensions based on Swagger, and provides related examples to describe implementation.

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

1. Swagger extensions:

The Swagger extensions are used to extend native Swagger Operation Object, providing features such as authentication, parameter mapping, and backend services. In addition, these extensions include the support for processing the ANY method in order to respond to requests made through any HTTP method.All extensions begin with x-aliyun-apigateway-, which are described as follows:

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

The authentication type is applied to Operation Object. The extension is used to specify the API authentication type.

Value range :

  • APP (Default): the application authentication for Alibaba Cloud API Gateway.
  • ANONYMOUS: Anonymous

Example:

  1. ...
  2. paths:
  3. 'path/':
  4. get:
  5. x-aliyun-apigateway-auth-type: ANONYMOUS
  6. ...

1.2 x-aliyun-apigateway-paramater-handling: API mapping relationship

The API mapping relationship applied to the Operation Object, is used to specify the mapping relationship between the request parameters and the backend service parameters. When you select PASSTHROUGH as the mapping relationship, the Parameter Objectdoes not support x-aliyun-apigateway-backend-location and x-aliyun-apigateway-backend-name properties.

Value range :

  • PASSTHROUGH (Default): the request parameter passthrough.
  • MAPPING: the request parameter mapping.

Example:

  1. ...
  2. paths:
  3. 'path/':
  4. get:
  5. x-aliyun-apigateway-paramater-handling: MAPPING
  6. ...

1.3 x-aliyun-apigateway-backend: backend type

The backend type applied to Operation Object. The parameter is used to specify backend service information. According to the backend service type, the specific properties are as follows:

1.3.1 Backend service type: HTTP

The HTTP backend type is used to configure the service address to achieve direct backend service access.

Property description:

Property name Type Description
type string Required. The value is HTTP.
address string Required. The address of the backend service.
path string Required. The path of the backend service. Support the path variable.
method string Required. The backend request method.
timeout int Optional. The default value is 10,000. The property value range is[500,30000]

Example:

  1. ...
  2. x-aliyun-apigateway-backend:
  3. type: HTTP
  4. address: http://10.10.100.2:8000
  5. path: "/users/{userId}"
  6. method: GET
  7. timeout: 7,000
  8. ...

1.3.2 Backend service type: HTTP-VPC

The HTTP-VPC backend type is deployed when the backend service is running in the VPC network. You need to Create a VPC authorization, and then import through the VPC authorized name.

Property description:

Property name Type Description
type string Required. The value is HTTP-VPC.
vpcAccessName string Required. The VPC network name that is used by the backend service.
path string Required. Specify the backend service path. Support the path variable.
method string Required. The backend request method.
timeout int Optional. The default value is 10,000. The property value range is[500,30000]

Example:

  1. ...
  2. x-aliyun-apigateway-backend:
  3. type: HTTP_VPC
  4. vpcAccessName: vpcAccess1
  5. path: "/users/{userId}"
  6. method: GET
  7. timeout: 10,000
  8. ...

1.3.3 Backend service type: FC

The FC backend type is used to configure the service address to Function Compute backend service access.

Property description:

Property name Type Description
type string Required;The value is FC
fcRegion string Required: The region that FC belongs to
serviceName string Required: The service name of current FC
functionName string Required:The function name of current FC
arn string Required: Arn of the current FC.

Example:

  1. ...
  2. x-aliyun-apigateway-backend:
  3. type: FC
  4. fcRegion: cn-shanghai
  5. serviceName: fcService
  6. functionName: fcFunction
  7. arn: acs:ram::111111111:role/aliyunapigatewayaccessingfcrole
  8. ...

1.3.4 Backend service type: MOCK

The MOCK backend type is used to simulate the backend service call by returning the default response.

Property description:

Property name Type Description
type string Required. The value is MOCK.
mockResult string Required. The response result of MOCK.

Example:

  1. ...
  2. x-aliyun-apigateway-backend:
  3. type: MOCK
  4. mockResult: mock resul sample
  5. ...

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

A constant parameter applied toOperation Object is used to specify the parameter applied to the backend service.

Property description:

Property name Type Description
backendName string Required. The backend parameter name.
value string Required. The constant value.
location String Required. The location of the constant parameter. You can specify[query,header]
description string Optional. The description of the constant parameter.

Example:

  1. ...
  2. x-aliyun-apigateway-constant-parameters:
  3. - backendName: swaggerConstant
  4. value: swaggerConstant
  5. location: header
  6. description: description of swagger
  7. ...

1.5 x-aliyun-apigateway-system-parameters: the backend service parameters.

A backend service parameter applied to Operation Object is used to define the system parameters of the API backend service.

Property description:

Property name Type Description
systemName string Required. The system parameter name.
backendName string Required. The backend parameter name.
location String Required. The location of the constant parameter. You can specify[query,header]

Example:

  1. ...
  2. x-aliyun-apigateway-system-parameters:
  3. - systemName: CaAppId
  4. backendName: appId
  5. location: header
  6. ...

1.6 x-aliyun-apigateway-backend-location: the backend parameter location.

The backend parameter location is applied Parameter Object. The property applies only when the setting is x-aliyun-apigateway-paramater-handling: MAPPING. After the parameter mapping is set, the property is used to specify the parameter location when the backend service sends a request.

Value range :

  • path
  • header
  • query
  • formData

Example:

  1. ...
  2. parameters:
  3. - name: swaggerHeader
  4. in: header
  5. required: false
  6. type: number
  7. format: double
  8. minimum: 0.1
  9. maximum: 0.5
  10. x-aliyun-apigateway-backend-location: query
  11. x-aliyun-apigateway-backend-name: backendQuery
  12. ...

1.7 x-aliyun-apigateway-backend-name: the backend parameter name.

The backend parameter name is applied to Parameter Object. This property applies only when the setting is x-aliyun-apigateway-paramater-handling: MAPPING. After the parameter mapping is set, the property is used to specify the parameter name when the backend service sends a request.

Example:

  1. ...
  2. parameters:
  3. - name: swaggerHeader
  4. in: header
  5. required: false
  6. type: number
  7. format: double
  8. minimum: 0.1
  9. maximum: 0.5
  10. x-aliyun-apigateway-backend-location: query
  11. x-aliyun-apigateway-backend-name: backendQuery
  12. ...

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

The ANY method is applied to Path Item Object. The method sets an API to accept any type of HTTP request.

Example:

  1. ...
  2. paths:
  3. 'path/':
  4. x-aliyun-apigateway-any-method:
  5. ...
  6. ...

2. Compatibility

The differences between API Gateway and the Swagger specification when defining APIs are as follows:

2.1 Comparison between Swagger parameter types and original API Gateway type

Swagger type API Gateway type Supported verification parameters and rules
  • 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 -

3. Swagger example

This topic provides three examples of Swagger extensions that are based on 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 only for your reference.

3.1 Swagger example with HTTP as the API Gateway backend service

  1. swagger: '2.0'
  2. basePath: /
  3. info:
  4. version: '0.9'
  5. title: Aliyun Api Gateway Swagger Sample
  6. schemes:
  7. - http
  8. - https
  9. paths:
  10. '/http/get/mapping/{userId}':
  11. get:
  12. operationId: case1
  13. schemes:
  14. - http
  15. - https
  16. x-aliyun-apigateway-paramater-handling: MAPPING
  17. x-aliyun-apigateway-auth-type: ANONYMOUS
  18. x-aliyun-apigateway-backend:
  19. type: HTTP
  20. address: 'http://www.aliyun.com'
  21. path: '/builtin/echo/{userId}'
  22. method: get
  23. timeout: 10000
  24. parameters:
  25. - name: userId
  26. in: path
  27. required: true
  28. type: string
  29. - name: swaggerQuery
  30. in: query
  31. required: false
  32. default: '123465'
  33. type: integer
  34. format: int32
  35. minimum: 0
  36. maximum: 100
  37. - name: swaggerHeader
  38. in: header
  39. required: false
  40. type: number
  41. format: double
  42. minimum: 0.1
  43. maximum: 0.5
  44. x-aliyun-apigateway-backend-location: query
  45. x-aliyun-apigateway-backend-name: backendQuery
  46. x-aliyun-apigateway-constant-parameters:
  47. - backendName: swaggerConstant
  48. value: swaggerConstant
  49. location: header
  50. description: description of swagger
  51. x-aliyun-apigateway-system-parameters:
  52. - systemName: CaAppId
  53. backendName: appId
  54. location: header
  55. responses:
  56. '200':
  57. description: 200 description
  58. '400':
  59. description: 400 description
  60. '/echo/test/post/{userId}':
  61. post:
  62. operationId: testpost
  63. schemes:
  64. - http
  65. - https
  66. x-aliyun-apigateway-paramater-handling: MAPPING
  67. x-aliyun-apigateway-backend:
  68. type: HTTP
  69. address: 'http://www.aliyun.com'
  70. path: '/builtin/echo/{backend}'
  71. method: post
  72. timeout: 10000
  73. consumes:
  74. - application/x-www-form-urlencoded
  75. parameters:
  76. - name: userId
  77. required: true
  78. in: path
  79. type: string
  80. x-aliyun-apigateway-backend-name: backend
  81. - name: swaggerQuery1
  82. in: query
  83. required: false
  84. default: '123465'
  85. type: integer
  86. format: int32
  87. minimum: 0
  88. maximum: 100
  89. x-aliyun-apigateway-enum: 1,2,3
  90. - name: swaggerQuery2
  91. in: query
  92. required: false
  93. type: string
  94. x-aliyun-apigateway-backend-location: header
  95. x-aliyun-apigateway-backend-name: backendHeader
  96. - name: swaggerHeader
  97. in: header
  98. required: false
  99. type: number
  100. format: double
  101. minimum: 0.1
  102. maximum: 0.5
  103. x-aliyun-apigateway-backend-location: query
  104. x-aliyun-apigateway-backend-name: backendQuery
  105. - name: swaggerFormdata
  106. in: formData
  107. required: true
  108. type: string
  109. responses:
  110. '200':
  111. description: 200 description
  112. '400':
  113. description: 400 description
  114. x-aliyun-apigateway-any-method:
  115. operationId: case2
  116. schemes:
  117. - http
  118. - https
  119. x-aliyun-apigateway-paramater-handling: MAPPING
  120. x-aliyun-apigateway-backend:
  121. type: HTTP
  122. address: 'http://www.aliyun.com'
  123. path: '/builtin/echo/{abc}'
  124. method: post
  125. timeout: 10000
  126. parameters:
  127. - name: userId
  128. in: path
  129. required: false
  130. default: '123465'
  131. type: integer
  132. format: int32
  133. minimum: 0
  134. maximum: 100
  135. x-aliyun-apigateway-backend-name: abc
  136. x-aliyun-apigateway-backend-location: path
  137. responses:
  138. '200':
  139. description: 200 description
  140. '400':
  141. description: 400 description

3.2 Swagger example with HTTP-VPC as the API Gateway backend service

  1. swagger: '2.0'
  2. basePath: /
  3. info:
  4. version: '0.9'
  5. title: Aliyun Api Gateway Swagger Sample
  6. schemes:
  7. - http
  8. - https
  9. paths:
  10. '/http/get/mapping/{userId}':
  11. get:
  12. operationId: case1
  13. schemes:
  14. - http
  15. - https
  16. x-aliyun-apigateway-paramater-handling: MAPPING
  17. x-aliyun-apigateway-backend:
  18. type: HTTP-VPC
  19. vpcAccessName: vpcName1
  20. path: '/builtin/echo/{userId}'
  21. method: get
  22. timeout: 10000
  23. parameters:
  24. - name: userId
  25. in: path
  26. required: true
  27. type: string
  28. - name: swaggerQuery
  29. in: query
  30. required: false
  31. default: '123465'
  32. type: integer
  33. format: int32
  34. minimum: 0
  35. maximum: 100
  36. - name: swaggerHeader
  37. in: header
  38. required: false
  39. type: number
  40. format: double
  41. minimum: 0.1
  42. maximum: 0.5
  43. x-aliyun-apigateway-backend-location: query
  44. x-aliyun-apigateway-backend-name: backendQuery
  45. responses:
  46. '200':
  47. description: 200 description
  48. '400':
  49. description: 400 description
  50. '/echo/test/post':
  51. post:
  52. operationId: testpost
  53. schemes:
  54. - http
  55. - https
  56. x-aliyun-apigateway-paramater-handling: MAPPING
  57. x-aliyun-apigateway-backend:
  58. type: HTTP-VPC
  59. vpcAccessName: vpcName2
  60. path: '/builtin/echo'
  61. method: post
  62. timeout: 10000
  63. consumes:
  64. - application/x-www-form-urlencoded
  65. parameters:
  66. - name: swaggerQuery1
  67. in: query
  68. required: false
  69. default: '123465'
  70. type: integer
  71. format: int32
  72. minimum: 0
  73. maximum: 100
  74. - name: swaggerQuery2
  75. in: query
  76. required: false
  77. type: string
  78. x-aliyun-apigateway-backend-location: header
  79. x-aliyun-apigateway-backend-name: backendHeader
  80. - name: swaggerHeader
  81. in: header
  82. required: false
  83. type: number
  84. format: double
  85. minimum: 0.1
  86. maximum: 0.5
  87. x-aliyun-apigateway-backend-location: query
  88. x-aliyun-apigateway-backend-name: backendQuery
  89. - name: swaggerFormdata
  90. in: formData
  91. required: true
  92. type: string
  93. responses:
  94. '200':
  95. description: 200 description
  96. '400':
  97. description: 400 description
  98. x-aliyun-apigateway-any-method:
  99. operationId: case2
  100. schemes:
  101. - http
  102. - https
  103. x-aliyun-apigateway-paramater-handling: PASSTHROUGH
  104. x-aliyun-apigateway-backend:
  105. type: HTTP-VPC
  106. vpcAccessName: vpcName3
  107. path: '/builtin/echo'
  108. method: post
  109. timeout: 10000
  110. responses:
  111. '200':
  112. description: 200 description
  113. '400':
  114. description: 400 description

3.3 Swagger example with Function Compute as the API Gateway backend service

  1. swagger: '2.0'
  2. basePath: /
  3. info:
  4. version: '0.9'
  5. title: Aliyun Api Gateway Swagger Sample
  6. schemes:
  7. - http
  8. - https
  9. paths:
  10. '/http/get/mapping/{userId}':
  11. get:
  12. operationId: case1
  13. schemes:
  14. - http
  15. - https
  16. x-aliyun-apigateway-paramater-handling: MAPPING
  17. x-aliyun-apigateway-backend:
  18. type: FC
  19. fcRegion: cn-shanghai
  20. serviceName: fcService
  21. functionName: fcFunction
  22. arn: acs:ram::111111111:role/aliyunapigatewayaccessingfcrole
  23. parameters:
  24. - name: userId
  25. in: path
  26. required: true
  27. type: string
  28. responses:
  29. '200':
  30. description: 200 description
  31. '400':
  32. description: 400 description

3.4 Swagger example with MOCK as the API Gateway backend service

  1. swagger: '2.0'
  2. basePath: /
  3. info:
  4. version: '0.9'
  5. title: Aliyun Api Gateway Swagger Sample
  6. schemes:
  7. - http
  8. paths:
  9. '/mock/get/mapping/{userId}':
  10. get:
  11. operationId: case1
  12. schemes:
  13. - http
  14. - https
  15. x-aliyun-apigateway-paramater-handling: MAPPING
  16. x-aliyun-apigateway-backend:
  17. type: MOCK
  18. mockResult: mock resul sample
  19. mockStatusCode: 200
  20. mockHeaders:
  21. - name: server
  22. value: mock
  23. - name: proxy
  24. value: GW
  25. parameters:
  26. - name: userId
  27. in: path
  28. required: true
  29. type: string
  30. responses:
  31. '200':
  32. description: 200 description
  33. '400':
  34. description: 400 description