swagger扩展注释API详细说明

Swagger扩展
 
• 1  x-any-method:Any接受所有请求类型
 
含义:Paths Object 属性扩展,表示该API接受所有HTTP请求类型。

...

  paths:

    '/path':

    x-any-method: Any

  ...

...

参数说明

参数

是否必选

类型

说明

x-any-method

String

在取值为Any时,表示可接受的API请求类型。

• 2  x-request-type:API请求类型

含义属性扩展,表示该API是否可以上架到云市场。

示例

...

paths:

  '/path':

    get:

      x-request-type: PRIVATE

...

参数说明

参数

是否必选

类型

说明

x-request-type

String

API的请求类型,该API是否可以上架云市场,目前支持:

  • PRIVITE:私有型,不上架云市场。
  • PUBLIC:公有型,上架云市场。

 • 3  x-auth-type:安全认证类型

含义属性扩展,表示该API在平安云网关安全认证类型。

示例

   ...

   paths:

     '/path':

       get:

         x-auth-type: APP_AUTH

   ...

参数说明

参数

是否必选

类型

说明

x-auth-type

String

API网关的安全认证类型,目前支持:

  • APP_AUTH:调用API时,由阿里云API网关服务负责对应用进行安全认证。
  • NO_AUTH:不需要认证。任何可以获取此API的应用,均可以调用。

• 4   x-signature-algorithm:签名算法

含义 属性扩展,表示该API所使用的签名算法,当安全认证类型为APP_AUTH时需要设置该属性。

示例

...

paths:

  '/path':

    get:

      x-signature-algorithm: H_MAC_SHA1

...

参数说明

参数

是否必选

类型

说明

x-signature-algorithm

String

API网关支持的签名算法:

  • H_MAC_SHA1
  • H_MAC_SHA256

• 5  x-path-match-type:匹配模式

含义 属性扩展,表示该API的路径匹配模式。

示例:

...

paths:

  '/path':

    get:

      x-path-match-type: PREFIX

...

参数说明

参数

是否必选

类型

说明

x-path-match-type

String

请求路径的匹配模式,目前支持:

•   NORMAL:完整路径匹配,调用的请求路径需要与创建API时设置的请求PATH完全一致。

•   PREFIX:前缀路径匹配,调用的请求路径以创建API时设置的请求PATH为前缀

    例如:/getUserInfo/test/AAA或/getUserInfo/test/BBB均可匹配到/getUserInfo/test,但不会匹配/getUserInfotest。

• 6  x-request-cors:跨域

含义:属性扩展,表示该API是否支持跨域。

示例:

...

paths:

  '/path':

     get:

       x-request-cors: true

...

参数说明

参数

是否必选

类型

说明

x-request-cors

String

是否支持跨域,默认情况是false:

•   true:支持跨域

•   false:不支持跨域

• 7  x-body-desc:请求体描述

含义属性扩展,用于描述API请求体内容。

示例

...

paths:

  '/path':

     post:

       x-body-desc: The description of request body

...

参数说明

参数

是否必选

类型

说明

x-body-desc

String

请求体描述。

请求方法可以是POST、PUT、PATCH、ANY等。

 • 8  入参定义示例

含义属性扩展,用于描述API请求参数的示例。

示例

...

paths:

  '/path':

     get:

       parameters:

         - {description: request param in header, in: header, name: reqHeader, required: false,

         default: pingan, type: string, x-example: apigateway}

...

参数说明

参数

是否必选

类型

说明

description

string

参数的相关描述信息。

name

string

参数的名称。

in

string

参数的位置,支持:path、query、header。

type

string

参数的属性值类型,支持:string、integer、number、boolean。

required

string

参数的属性值是否必填:

•  true:必填

•  false:可选

default

string

参数属性值的默认情况,当required为true时需要设置。

x-example

string

参数的属性值示例。

• 9  x-backend-parameters:后端服务参数

含义属性扩展,用于指定API入参定义与后端服务参数的映射关系。

.yaml文件格式示例

...

  parameters:

  - name: reqPath

    in: path

    required: true

    type: string

    x-backend-parameters:

    - {location: path, name: backPath}

    x-example: apigateway

    description: request param in path

...

.json文件格式示例

...

  "parameters":[

      {

          "name":"reqPath",

          "in":"path",

          "required":true,

          "type":"string",

          "description":"request param in path",

          "x-backend-parameters":[

              {

                  "location":"path",

                  "name":"backPath"

              }

          ],

          "x-example":"apigateway"

      }

  ],

...

参数说明

后端服务参数依赖于入参参数,当定义有入参参数时,可将该参数映射为后端参数

参数

是否必选

类型

说明

location

string

后端服务参数的位置,目前支持:path、query、header。

name

string

后端服务参数的名称。

• 10  x-backend:后端服务类型

含义 属性扩展,用于描述API后端服务类型。

参数说明

参数

是否必选

类型

说明

x-backend

string

后端服务类型,目前支持:HTTP/ HTTPS、MOCK

• 10.1  HTTP后端服务类型

含义:后端服务类型HTTP/ HTTPSAPI网关可转发HTTP/HTTPS协议的请求

示例

...

x-backend:

- {address:'http://10.10.10.10:8888',method:ANY,path:'/back/{backPath}/{consPath}/{sysPath}',timeout: 6000, type: HTTP}

...

参数说明

参数

是否必选

类型

说明

type

string

后端服务类型:HTTP。

address

string

后端服务的地址。

path

string

后端服务的请求路径。

method

string

后端服务的请求方法:目前支持:GET、POST、PUT、DELETE、HEAD、OPTIONS、PATCH、ANY。

timeout

integer

后端请求超时阈值,取值范围:1-600000ms,默认情况是5000ms。

x-constant-parameters

Constatnt Object

常量参数

x-system-parameters

System Object

系统参数

• 10.2  MOCK后端服务类型

含义:后端服务类型MOCK时,主要用于API的调试环境,不调用后端服务,直接返回设置的结果给API调用方

示例

...        

 x-backend:

   mockHeaders:

   - {name: PA001, value: 平安集团}

   - {name: PA011, value: 平安科技}

   mockResult: mock result

   type: MOCK

...

参数说明

参数

是否必选

类型

说明

type

string

后端服务类型:MOCK。

mockResult

string

Mock返回结果。

mockHeaders

MockHeader Object

Mock响应头,可参考mockHeaders。

• 10.2.1  mockHeaders:Mock响应头参数

含义MOCK响应头数据定义。

示例

...

  mockHeaders:

  - {name: PA011, value: 平安科技}

...

参数说明

参数

是否必选

类型

说明

name

string

MOCK响应头的参数名称。

value

string

MOCK响应头的参数取值。

• 11 常量参数

含义属性扩展,在后端服务类型为HTTP时,可设置API网关的常量参数。

示例

...

  x-constant-parameters:

  - {name: conPa, location: query, value: apigateway, description: The constant parameter in backend}

...

参数说明

参数

是否必选

类型

说明

name

string

常量参数的名称。

value

string

常量参数的取值。

location

string

常量参数的位置,目前支持:path、query、header。

description

string

常量参数的相关描述信息。

• 12  系统参数

含义属性扩展,在后端服务类型为HTTP时,可设置API网关的系统参数。

示例

...

  x-system-parameters:

  - {name: sysPa, location: query, value: PA-AG-RequestId}

...

参数说明

参数

是否必选

类型

说明

name

string

系统参数的名称。

value

string

系统参数的取值:目前支持:

  • PA-AG-RequestId:客户端发送或API网关生成的API请求标识ID。
  • PA-AG-Timestamp:客户端发送API请求时的时间戳。
  • PA-AG-Env:客户端调用API的环境,默认情况是线上环境release。
  • PA-AG-ClientIP:客户端的IP地址。
  • PA-AG-AppId:客户端使用的应用(APP)的标识ID。
  • PA-AG-GroupId:客户端调用的API所属分组的标识ID。
  • PA-AG-UserId:客户端使用的应用(APP)的所属账户ID(TenantUUID)。
  • PA-AG-Gateway-ChargeMode:调用API时付费模式。
  • PA-AG-Gateway-Timestamp:API网关接受并处理API请求的时间戳。

location

string

系统参数的位置,目前支持:path、query、header。

• 13  x-response-content-type:返回结果的内容类型

含义属性扩展,用于描述返回Content-type类型。

示例

...

paths:

  '/path':

    get:

      x-response-content-type: application/xml;charset=utf-8

...

参数说明

参数

是否必选

类型

说明

x-response-content-type

string

调用API返回结果的内容类型,目前支持:

  • application/json;charset=utf-8:JSON格式。
  • text/plain;charset=utf-8:纯文本格式。
  • application/octet-stream;charset=utf-8:二进制流格式。
  • application/xml;charset=utf-8:XML解析格式。
  • text/html;charset=utf-8:HTML解析格式。
  • passthrough:透传Content-type。

• 14  x-response-success-result:成功的返回结果

含义属性扩展,用于描述调用API成功时的返回结果。

示例

...

paths:

  '/path':

    get:

      x-response-success-result: success

...

参数说明

参数

是否必选

类型

说明

x-response-success-result

string

调用API成功,返回的响应结果。

• 15  x-response-failure-result:失败的返回结果

含义属性扩展,用于描述调用API失败时的返回结果。

示例

...

paths:

  '/path':

    get:

      x-response-failure-result: error

...

参数说明

参数

是否必选

类型

说明

x-response-failure-result

string

调用API失败,返回的响应结果。

• 16  x-description:错误码

含义属性扩展,用于描述调用API出错时的错误信息。

示例:

...

paths:

  '/path':

    get:

      responses:

        '200': {description: success, x-description: 'success'}

...

参数说明

参数

是否必选

类型

说明

x-description

string

调用API出错时的错误码,可作为排查报错信息的索引。