全部产品
云市场

通过导入Swagger创建API

更新时间:2019-04-29 11:35:53

Swagger是一种用于描述API定义的规范,被广泛应用于定义和描述后端应用服务的API。现在,API网关支持导入Swagger 2.0的文件来创建API,您可以参考ImportSwagger,或在控制台上进行操作,入口见下图:

API网关的Swagger扩展基于Swagger 2.0,可以创建API实体的Swagger定义,并将Swagger导入API网关用于批量创建或者更新API实体。API网关的预配置是swagger2.0,它可支持并兼容大部分的Swagger规范,但存在一定的差异性(Swagger兼容性说明)。

本章节主要对基于Swagger的API网关扩展进行介绍,并提供相应的示例来阐述用法。

注:Swagger中所有参数与取值均大小写敏感

一、Swagger扩展 :

Swagger扩展主要是对于swagger原生Operation Object进行扩展,增加认证、参数映射以及后端服务等扩展。除此之外,增加处理any方法的扩展,用于捕获任意http请求方法。所有扩展均以x-aliyun-apigateway-开头,具体扩展内容如下:

1.1 x-aliyun-apigateway-auth-type: 授权类型

授权类型,应用于Operation Object。用于指定该API的授权类型,其中:

取值范围:

  • APP(默认值): 阿里云API网关APP授权
  • ANONYMOUS: 匿名

示例

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

1.3 x-aliyun-apigateway-api-market-enable: 云市场支持

授权类型,应用于Operation Object。用于指定该API是否可以上架云市场,其中:

取值范围:

  • true
  • false(默认)

示例

  1. ...
  2. paths:
  3. 'path/':
  4. get:
  5. x-aliyun-apigateway-api-market-enable: true
  6. ...

1.4 x-aliyun-apigateway-api-force-nonce-check: 强制NONCE校验

授权类型,应用于Operation Object。用于指定该API是否进行NONCE强制校验,其中:

取值范围:

  • true
  • false(默认)

示例

  1. ...
  2. paths:
  3. 'path/':
  4. get:
  5. x-aliyun-apigateway-api-force-nonce-check: true
  6. ...

1.5 x-aliyun-apigateway-paramater-handling: API映射关系

API映射关系, 应用于Operation Object,用于指定请求参数与后端服务参数的映射关系。当映射关系选择PASSTHROUGH时,Parameter Object不支持 x-aliyun-apigateway-backend-locationx-aliyun-apigateway-backend-name 属性。

取值范围:

  • PASSTHROUGH(默认值): 入参透传
  • MAPPING: 入参映射

示例

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

1.6 x-aliyun-apigateway-backend: 后端类型

后端类型, 应用于Operation Object。用于设置后端服务信息。根据后端服务类型,决定具体的属性,详情如下:

1.6.1 后端服务类型:HTTP

HTTP的后端类型用于直接配置后端服务地址,一般用于后端地址可以直接访问的场合。

属性说明:

属性名称 类型 描述
type string 必填;值为HTTP
address string 必填;用于标识后端服务地址
path string 选填:用于标识后端服务路径。支持路径变量。默认与跟path值相同
method string 必填:后端请求方法
timeout int 选填,默认为10000。该属性取值范围为[500,30000]

示例:

  1. ...
  2. x-aliyun-apigateway-backend:
  3. type: HTTP
  4. address: 'http://www.aliyun.com'
  5. path: '/builtin/echo'
  6. method: get
  7. timeout: 10000
  8. ...

1.6.2 后端服务类型:HTTP-VPC

HTTP-VPC的后端类型用于后端服务在VPC网络内的场合,需要先创建VPC授权,使用VPC授权名导入。

属性说明:

属性名称 类型 描述
type string 必填;值为:HTTP-VPC
vpcAccessName string 必填;后端服务使用的vpc实例名称
path string 选填:用于标识后端服务路径。支持路径变量。默认与根path相等
method string 必填:后端请求方法
timeout int 选填,默认为10000。该属性取值范围为[500,30000]

示例:

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

1.6.3 后端服务类型:FC

API网关后端服务类型为FUNCTION COMPUTE。

属性说明:

属性名称 类型 描述
type string 必填;值为:FC
fcRegion string 必填;函数计算所在区域
serviceName string 必填: 函数计算服务名
functionName string 必填:函数计算函数名
arn string 选填,函数计算RAM授权

示例:

  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.6.4 后端服务类型: MOCK

MOCK的后端类型,用来模拟最初预定的返回结果。

属性说明:

属性名称 类型 描述
type string 必填;值为:MOCK
mockResult string 必填;mock返回结果
mockStatusCode Integer 选填
mockHeaders Header 选填

Header 的 说明

属性名称 类型 描述
name string 必填
value string 必填

示例:

  1. ...
  2. x-aliyun-apigateway-backend:
  3. type: MOCK
  4. mockResult: mock resul sample
  5. mockStatusCode: 200
  6. mockHeaders:
  7. - name: server
  8. value: mock
  9. - name: proxy
  10. value: GW
  11. ...

1.7 x-aliyun-apigateway-constant-parameters: 常量参数

常量参数, 应用于Operation Object,用于定义后端服务的常量参数。

属性说明:

属性名称 类型 描述
backendName string 必填;后端参数名称
value string 必填;常量值
location String 必填;常量参数存放位置,可选值:[query,header]
description string 可选;用于对该常量进行说明

示例:

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

1.8 x-aliyun-apigateway-system-parameters: 后端服务参数

后端服务参数, 应用于Operation Object,用于定义API后端服务的系统参数。

属性说明:

属性名称 类型 描述
systemName string 必填;系统参数名称
backendName string 必填;后端参数名称
location String 必填;常量参数存放位置,可选值:[query,header]

示例:

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

1.9 x-aliyun-apigateway-backend-location: 后端参数位置

后端参数位置, 应用于 Parameter Object。该属性仅在 x-aliyun-apigateway-paramater-handling: MAPPING设置时生效,用于设置参数映射后,在后端服务请求时的参数位置。

取值范围:

  • path
  • header
  • query
  • formData

示例:

  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.10 x-aliyun-apigateway-backend-name: 后端参数名称

后端参数名称, 应用于Parameter Object。该属性仅在 x-aliyun-apigateway-paramater-handling: MAPPING设置时生效,用于设置参数映射后,在后端服务请求时的参数名称。

示例:

  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.11 x-aliyun-apigateway-query-schema: query对Model支持

后端参数名称, 应用于Parameter Object。用于对Query进行模型定义。当parameter为String类型,同时定义为query参数时,可以使用。

示例:

  1. ...
  2. parameters:
  3. - name: event_info
  4. in: query
  5. required: true
  6. type: string
  7. x-aliyun-apigateway-query-schema:
  8. $ref: "#/definitions/EvnetInfo"
  9. ...

1.12 x-aliyun-apigateway-any-method: ANY方法

ANY方法, 应用于Path Item Object,用于设置API可以接受任意类型的http请求。

示例

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

1.13 x-aliyun-apigateway-app-code-type: Appcode简单认证

Appcode简单认证,应用于Operation Object。用于指定该API是否支持APPcode简单认证,其中:

取值范围:

  • DEFAULT(默认值)
  • DISABLE: 禁用
  • HEADER: 通过HEADER传入appcode
  • HEADER_QUERY: 可以通过HEADER或Qeury传入appcode

示例

  1. ...
  2. paths:
  3. 'path/':
  4. get:
  5. x-aliyun-apigateway-app-code-type: HEADER
  6. ...

二、兼容性说明

API网关与Swagger规范在定义API时存在一定差异性,包括:

2.1 Swagger参数类型与原有API网关类型的对照表

Swagger类型 API网关类型 支持的校验参数及规则
  • 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 consumes字段支持

当Swagger配置文件存在formdata类型参数时,需要配置consumes节点。API网关现在只支持application/x-www-form-urlencoded类型。

  1. consumes:
  2. - application/x-www-form-urlencoded

三、Swagger示例

本章节提供三个基于API网关的swagger扩展示例。示例几乎涵盖了所有的扩展内容,为基于swagger扩展自定义API实体提供便利。

注:示例仅供参考。

3.1 API网关后端服务为HTTP的Swagger示例

  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. x-aliyun-apigateway-paramater-handling: MAPPING
  10. x-aliyun-apigateway-api-market-enable: true
  11. x-aliyun-apigateway-api-force-nonce-check: true
  12. x-aliyun-apigateway-backend:
  13. type: HTTP
  14. address: 'http://www.aliyun.com'
  15. method: get
  16. timeout: 10000
  17. paths:
  18. '/http/get/mapping/{userId}':
  19. get:
  20. operationId: case1
  21. schemes:
  22. - http
  23. - https
  24. x-aliyun-apigateway-paramater-handling: MAPPING
  25. x-aliyun-apigateway-api-market-enable: true
  26. x-aliyun-apigateway-auth-type: ANONYMOUS
  27. parameters:
  28. - name: userId
  29. in: path
  30. required: true
  31. type: string
  32. - name: swaggerQuery
  33. in: query
  34. required: false
  35. default: '123465'
  36. type: integer
  37. format: int32
  38. minimum: 0
  39. maximum: 100
  40. - name: swaggerHeader
  41. in: header
  42. required: false
  43. type: number
  44. format: double
  45. minimum: 0.1
  46. maximum: 0.5
  47. x-aliyun-apigateway-backend-location: query
  48. x-aliyun-apigateway-backend-name: backendQuery
  49. x-aliyun-apigateway-constant-parameters:
  50. - backendName: swaggerConstant
  51. value: swaggerConstant
  52. location: header
  53. description: description of swagger
  54. x-aliyun-apigateway-system-parameters:
  55. - systemName: CaAppId
  56. backendName: appId
  57. location: header
  58. responses:
  59. '200':
  60. description: 200 description
  61. '400':
  62. description: 400 description
  63. '/echo/test/post/{userId}':
  64. post:
  65. operationId: testpost
  66. schemes:
  67. - http
  68. - https
  69. x-aliyun-apigateway-paramater-handling: MAPPING
  70. x-aliyun-apigateway-backend:
  71. type: HTTP
  72. address: 'http://www.aliyun.com'
  73. method: post
  74. timeout: 10000
  75. consumes:
  76. - application/x-www-form-urlencoded
  77. parameters:
  78. - name: userId
  79. required: true
  80. in: path
  81. type: string
  82. - name: swaggerQuery1
  83. in: query
  84. required: false
  85. default: '123465'
  86. type: integer
  87. format: int32
  88. minimum: 0
  89. maximum: 100
  90. x-aliyun-apigateway-enum: 1,2,3
  91. - name: swaggerQuery2
  92. in: query
  93. required: false
  94. type: string
  95. x-aliyun-apigateway-backend-location: header
  96. x-aliyun-apigateway-backend-name: backendHeader
  97. x-aliyun-apigateway-query-schema:
  98. $ref: '#/definitions/AiGeneratePicQueryVO'
  99. - name: swaggerHeader
  100. in: header
  101. required: false
  102. type: number
  103. format: double
  104. minimum: 0.1
  105. maximum: 0.5
  106. x-aliyun-apigateway-backend-location: query
  107. x-aliyun-apigateway-backend-name: backendQuery
  108. - name: swaggerFormdata
  109. in: formData
  110. required: true
  111. type: string
  112. responses:
  113. '200':
  114. description: 200 description
  115. schema:
  116. $ref: '#/definitions/ResultOfGeneratePicturesVO'
  117. '400':
  118. description: 400 description
  119. x-aliyun-apigateway-any-method:
  120. operationId: case2
  121. schemes:
  122. - http
  123. - https
  124. x-aliyun-apigateway-paramater-handling: MAPPING
  125. x-aliyun-apigateway-backend:
  126. type: HTTP
  127. address: 'http://www.aliyun.com'
  128. path: '/builtin/echo/{abc}'
  129. method: post
  130. timeout: 10000
  131. parameters:
  132. - name: userId
  133. in: path
  134. required: false
  135. default: '123465'
  136. type: integer
  137. format: int32
  138. minimum: 0
  139. maximum: 100
  140. x-aliyun-apigateway-backend-name: abc
  141. x-aliyun-apigateway-backend-location: path
  142. responses:
  143. '200':
  144. description: 200 description
  145. '400':
  146. description: 400 description
  147. definitions:
  148. AiGeneratePicQueryVO:
  149. type: object
  150. properties:
  151. transactionId:
  152. type: string
  153. description: 异步任务ID
  154. GeneratePictureVO:
  155. type: object
  156. properties:
  157. id:
  158. type: integer
  159. format: int64
  160. description: 图片ID
  161. name:
  162. type: string
  163. description: 图片名称
  164. GeneratePicturesVO:
  165. type: object
  166. properties:
  167. failSize:
  168. type: integer
  169. format: int64
  170. description: 失败数量
  171. list:
  172. type: array
  173. description: 图片列表
  174. items:
  175. $ref: '#/definitions/GeneratePictureVO'
  176. title: GeneratePictureVO
  177. successSize:
  178. type: integer
  179. format: int32
  180. description: 成功数量
  181. totalSize:
  182. type: number
  183. format: float
  184. description: 请求总数
  185. ResultOfGeneratePicturesVO:
  186. type: object
  187. properties:
  188. model:
  189. description: 返回内容
  190. $ref: '#/definitions/GeneratePicturesVO'
  191. title: GeneratePicturesVO
  192. requestId:
  193. type: string
  194. description: 请求ID

3.2 API网关后端服务为HTTP-VPC的Swagger示例

  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 API网关后端服务为FunctionCompute的Swagger示例

  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 API网关后端服务为MOCK的Swagger示例

  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

四、特别说明

以下内容请密切关注,直接影响swagger的导入功能使用

4.1 全局域的支持

以下标签支持全局作用域的定义。当该标签原本作用域不存在该定义时,会自动填充全局域的定义值;若存在,则优先使用原本作用域的定义值。

  • x-aliyun-apigateway-backend
  • x-aliyun-apigateway-api-market-enable
  • x-aliyun-apigateway-api-force-nonce-check
  • x-aliyun-apigateway-paramater-handling
  • x-aliyun-apigateway-auth-type

4.2 Swagger Definition说明

swagger导入现在支持模型定义,但是与原有swagger规范存在差异模型的定义主要用于SDK的生成,所以会在原有swagger规范的基础上增加了一些限制条件:

  • swagger中schema标签仅支持:$ref类型
  • swagger中Definition的model仅支持object type类型的模型定义
  • swagger中Definition的model中存在array定义,其引用$ref应与title标签配合使用。array类型默认在SDK生成时对应生成ArrayList类型属性</li></ul>