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是否可以上架云市场,目前支持:
|
• 3 x-auth-type:安全认证类型
含义:属性扩展,表示该API在平安云网关安全认证类型。
示例:
... paths: '/path': get: x-auth-type: APP_AUTH ... |
参数说明:
参数 |
是否必选 |
类型 |
说明 |
x-auth-type |
是 |
String |
API网关的安全认证类型,目前支持:
|
• 4 x-signature-algorithm:签名算法
含义: 属性扩展,表示该API所使用的签名算法,当安全认证类型为APP_AUTH时需要设置该属性。
示例:
... paths: '/path': get: x-signature-algorithm: H_MAC_SHA1 ... |
参数说明:
参数 |
是否必选 |
类型 |
说明 |
x-signature-algorithm |
是 |
String |
API网关支持的签名算法:
|
• 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/ HTTPS时,API网关可转发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 |
系统参数的取值:目前支持:
|
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返回结果的内容类型,目前支持:
|
• 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出错时的错误码,可作为排查报错信息的索引。 |