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: 匿名

示例

...
paths:
  'path/':
    get:
      x-aliyun-apigateway-auth-type: ANONYMOUS
...
			
1.2 x-aliyun-apigateway-api-market-enable: 云市场支持

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

取值范围:

  • true
  • false(默认)

示例

...
paths:
  'path/':
    get:
      x-aliyun-apigateway-api-market-enable: true
...
			
1.3 x-aliyun-apigateway-api-force-nonce-check: 强制NONCE校验

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

取值范围:

  • true
  • false(默认)

示例

...
paths:
  'path/':
    get:
      x-aliyun-apigateway-api-force-nonce-check: true
...
			
1.4 x-aliyun-apigateway-parameter-handling: API映射关系

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

取值范围:

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

示例

...
paths:
  'path/':
    get:
      x-aliyun-apigateway-parameter-handling: MAPPING
...
			
1.5 x-aliyun-apigateway-backend: 后端类型

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

1.5.1 后端服务类型:HTTP

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

属性说明:

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

示例:

...
x-aliyun-apigateway-backend:
  type: HTTP
  address: 'http://www.aliyun.com'
  path: '/builtin/echo'
  method: get
  timeout: 10000
...
			

1.5.2 后端服务类型:HTTP-VPC

HTTP-VPC的后端类型用于后端服务在VPC网络内的场合,需要先创建VPC授权,具体操作请参考创建后端服务为VPC内资源的API使用VPC授权名导入。

属性说明:

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

示例:

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

1.5.3 后端服务类型:FC

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

属性说明:

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

示例:

...
x-aliyun-apigateway-backend:
  type: FC
  fcRegion: cn-shanghai
  serviceName: fcService
  functionName: fcFunction
  arn: acs:ram::111111111:role/aliyunapigatewayaccessingfcrole
...
			

1.5.4 后端服务类型: MOCK

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

属性说明:

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

Header 的说明

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

示例:

...
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: 常量参数

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

属性说明:

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

示例:

      ...
      x-aliyun-apigateway-constant-parameters:
        - backendName: swaggerConstant
          value: swaggerConstant
          location: header
          description: description of swagger
      ...
			
1.7 x-aliyun-apigateway-system-parameters: 后端服务参数

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

属性说明:

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

示例:

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

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

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

取值范围:

  • path
  • header
  • query
  • formData

示例:

     ...
      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: 后端参数名称

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

示例:

      ...
      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: query对Model支持

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

示例:

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

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

示例

...
paths:
  'path/':
     x-aliyun-apigateway-any-method:
     ...
...
			
1.12 x-aliyun-apigateway-app-code-type: Appcode简单认证

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

取值范围:

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

示例

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

二、兼容性说明

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
Double
  • 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类型。

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

三、Swagger示例

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

说明 示例仅供参考。
3.1 API网关后端服务为HTTP的Swagger示例
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: 异步任务ID
  GeneratePictureVO:
    type: object
    properties:
      id:
        type: integer
        format: int64
        description: 图片ID
      name:
        type: string
        description: 图片名称
  GeneratePicturesVO:
    type: object
    properties:
      failSize:
        type: integer
        format: int64
        description: 失败数量
      list:
        type: array
        description: 图片列表
        items:
          $ref: '#/definitions/GeneratePictureVO'
          title: GeneratePictureVO
      successSize:
        type: integer
        format: int32
        description: 成功数量
      totalSize:
        type: number
        format: float
        description: 请求总数
  ResultOfGeneratePicturesVO:
    type: object
    properties:
      model:
        description: 返回内容
        $ref: '#/definitions/GeneratePicturesVO'
        title: GeneratePicturesVO
      requestId:
        type: string
        description: 请求ID
			
3.2 API网关后端服务为HTTP-VPC的Swagger示例
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 API网关后端服务为FunctionCompute的Swagger示例
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 API网关后端服务为MOCK的Swagger示例
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的导入功能使用

4.1 全局域的支持

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

  • 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 Swagger Definition说明

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

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