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出错时的错误码，可作为排查报错信息的索引。 |