导入API网关的扩展Swagger定义

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

image

API网关的Swagger扩展基于Swagger 2.0,可以创建API实体的Swagger定义,并将Swagger导入API网关用于批量创建或者更新API实体。API网关的预配置是swagger2.0,它可支持并兼容大部分的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或Query传入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-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: 异步任务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