导入API网关的扩展Swagger定义 - API 网关

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

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-location 和 x-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