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.3 x-aliyun-apigateway-api-market-enable: 云市场支持

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

取值范围:

true
false(默认)

示例：

...
paths:
  'path/':
    get:
      x-aliyun-apigateway-api-market-enable: true
...

1.4 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.5 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.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]

示例:

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

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]

示例:

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

1.6.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.6.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.7 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.8 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.9 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.10 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.11 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.12 x-aliyun-apigateway-any-method: ANY方法

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

示例：

...
paths:
  'path/':
     x-aliyun-apigateway-any-method:
     ...
...

1.13 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	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类型。

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类型属性</li></ul><br />

原创文章，作者：网友投稿，如若转载，请注明出处：https://www.cloudads.cn/archives/33453.html

阿里云API 网关通过导入Swagger创建API

一、Swagger扩展 :

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

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

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

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

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

1.6.1 后端服务类型:HTTP

1.6.2 后端服务类型:HTTP-VPC

1.6.3 后端服务类型:FC

1.6.4 后端服务类型: MOCK

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

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

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

1.10 x-aliyun-apigateway-backend-name: 后端参数名称

1.11 x-aliyun-apigateway-query-schema: query对Model支持

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

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

二、兼容性说明

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

2.2 consumes字段支持

三、Swagger示例

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

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

3.3 API网关后端服务为FunctionCompute的Swagger示例

3.4 API网关后端服务为MOCK的Swagger示例

四、特别说明

4.1 全局域的支持

4.2 Swagger Definition说明

发表评论

阿里云API 网关通过导入Swagger创建API

一、Swagger扩展 :

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

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

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

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

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

1.6.1 后端服务类型:HTTP

1.6.2 后端服务类型:HTTP-VPC

1.6.3 后端服务类型:FC

1.6.4 后端服务类型: MOCK

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

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

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

1.10 x-aliyun-apigateway-backend-name: 后端参数名称

1.11 x-aliyun-apigateway-query-schema: query对Model支持

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

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

二、兼容性说明

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

2.2 consumes字段支持

三、Swagger示例

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

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

3.3 API网关后端服务为FunctionCompute的Swagger示例

3.4 API网关后端服务为MOCK的Swagger示例

四、特别说明

4.1 全局域的支持

4.2 Swagger Definition说明

相关推荐

发表评论

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