Swagger扩展

<p><span style="font-size:18px"><strong>&bull; 1&nbsp; x-any-method:Any接受所有请求类型</strong></span></p> <p><strong>含义</strong><strong>:</strong><a href="https://swagger.io/specification/v2/#pathsObject" target="_blank">Paths Object</a>&nbsp;属性扩展,表示该API接受所有HTTP请求类型。</p> <p><strong>示例</strong><strong>:</strong></p> <table border="0" cellpadding="0" cellspacing="0"> <tbody> <tr> <td style="background-color:#f7f8fa; vertical-align:top"> <p><span style="font-family:Consolas">...</span></p> <p><span style="font-family:Consolas">&nbsp; paths:</span></p> <p><span style="font-family:Consolas">&nbsp;&nbsp;&nbsp; &#39;/path&#39;:</span></p> <p><span style="font-family:Consolas">&nbsp;&nbsp;&nbsp; x-any-method: Any</span></p> <p><span style="font-family:Consolas">&nbsp; ...</span></p> <p><span style="font-family:Consolas">...</span></p> </td> </tr> </tbody> </table> <p><strong>参数说明</strong>:</p> <table border="1" cellpadding="0" cellspacing="0"> <tbody> <tr> <td style="background-color:#ededed; vertical-align:top"> <p><strong>参数</strong></p> </td> <td style="background-color:#ededed; vertical-align:top"> <p><strong>是否必选</strong></p> </td> <td style="background-color:#ededed; vertical-align:top"> <p><strong>类型</strong></p> </td> <td style="background-color:#ededed; vertical-align:top"> <p><strong>说明</strong></p> </td> </tr> <tr> <td style="vertical-align:top"> <p>x-any-method</p> </td> <td style="vertical-align:top"> <p>是</p> </td> <td style="vertical-align:top"> <p>String</p> </td> <td style="vertical-align:top"> <p>在取值为Any时,表示可接受的API请求类型。</p> </td> </tr> </tbody> </table> <p><span style="font-size:18px"><strong>&bull; 2&nbsp; x-request-type:API请求类型</strong></span></p> <p><strong>含义</strong><strong>:</strong><a href="https://swagger.io/specification/v2/#operationObject" target="_blank">Operation Object</a>&nbsp;属性扩展,表示该API是否可以上架到云市场。</p> <p><strong>示例</strong>:</p> <table border="0" cellpadding="0" cellspacing="0"> <tbody> <tr> <td style="background-color:#f7f8fa; vertical-align:top"> <p><span style="font-family:Consolas">...</span></p> <p><span style="font-family:Consolas">paths:</span></p> <p><span style="font-family:Consolas">&nbsp; &#39;/path&#39;:</span></p> <p><span style="font-family:Consolas">&nbsp;&nbsp;&nbsp; get:</span></p> <p><span style="font-family:Consolas">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; x-request-type: PRIVATE</span></p> <p><span style="font-family:Consolas">...</span></p> </td> </tr> </tbody> </table> <p><strong>参数说明</strong>:</p> <table border="1" cellpadding="0" cellspacing="0"> <tbody> <tr> <td style="background-color:#ededed; vertical-align:top"> <p><strong>参数</strong></p> </td> <td style="background-color:#ededed; vertical-align:top"> <p><strong>是否必选</strong></p> </td> <td style="background-color:#ededed; vertical-align:top"> <p><strong>类型</strong></p> </td> <td style="background-color:#ededed; vertical-align:top"> <p><strong>说明</strong></p> </td> </tr> <tr> <td style="vertical-align:top"> <p>x-request-type</p> </td> <td style="vertical-align:top"> <p>是</p> </td> <td style="vertical-align:top"> <p>String</p> </td> <td style="vertical-align:top"> <p>API的请求类型,该API是否可以上架云市场,目前支持:</p> <ul> <li>PRIVITE:私有型,不上架云市场。</li> <li>PUBLIC:公有型,上架云市场。</li> </ul> </td> </tr> </tbody> </table> <p>&nbsp;<strong><span style="font-size:18px">&bull; 3&nbsp; x-auth-type:安全认证类型</span></strong></p> <p><strong>含义</strong><strong>:</strong><a href="https://swagger.io/specification/v2/#operationObject" target="_blank">Operation Object</a>&nbsp;属性扩展,表示该API在平安云网关安全认证类型。</p> <p><strong>示例</strong>:</p> <table border="0" cellpadding="0" cellspacing="0"> <tbody> <tr> <td style="background-color:#f7f8fa; vertical-align:top"> <p><span style="font-family:Consolas">&nbsp;&nbsp; ...</span></p> <p><span style="font-family:Consolas">&nbsp;&nbsp; paths:</span></p> <p><span style="font-family:Consolas">&nbsp;&nbsp;&nbsp;&nbsp; &#39;/path&#39;:</span></p> <p><span style="font-family:Consolas">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; get:</span></p> <p><span style="font-family:Consolas">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; &nbsp;&nbsp;&nbsp;x-auth-type: APP_AUTH</span></p> <p><span style="font-family:Consolas">&nbsp;&nbsp; ...</span></p> </td> </tr> </tbody> </table> <p><strong>参数说明</strong>:</p> <table border="1" cellpadding="0" cellspacing="0"> <tbody> <tr> <td style="background-color:#ededed; vertical-align:top"> <p><strong>参数</strong></p> </td> <td style="background-color:#ededed; vertical-align:top"> <p><strong>是否必选</strong></p> </td> <td style="background-color:#ededed; vertical-align:top"> <p><strong>类型</strong></p> </td> <td style="background-color:#ededed; vertical-align:top"> <p><strong>说明</strong></p> </td> </tr> <tr> <td style="vertical-align:top"> <p>x-auth-type</p> </td> <td style="vertical-align:top"> <p>是</p> </td> <td style="vertical-align:top"> <p>String</p> </td> <td> <p>API网关的安全认证类型,目前支持:</p> <ul> <li>APP_AUTH:调用API时,由平安云API网关服务负责对应用进行安全认证。</li> <li>NO_AUTH:不需要认证。任何可以获取此API的应用,均可以调用。</li> </ul> </td> </tr> </tbody> </table> <p><span style="font-size:18px"><strong>&bull; 4&nbsp; &nbsp;x-signature-algorithm:签名算法</strong></span></p> <p><strong>含义</strong><strong>:</strong><a href="https://swagger.io/specification/v2/#operationObject" target="_blank">Operation Object</a>&nbsp;属性扩展,表示该API所使用的签名算法,当安全认证类型为APP_AUTH时需要设置该属性。</p> <p><strong>示例</strong>:</p> <table border="0" cellpadding="0" cellspacing="0"> <tbody> <tr> <td style="background-color:#f7f8fa; vertical-align:top"> <p><span style="font-family:Consolas">...</span></p> <p><span style="font-family:Consolas">paths:</span></p> <p><span style="font-family:Consolas">&nbsp; &#39;/path&#39;:</span></p> <p><span style="font-family:Consolas">&nbsp;&nbsp;&nbsp; get:</span></p> <p><span style="font-family:Consolas">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; x-signature-algorithm: H_MAC_SHA1</span></p> <p><span style="font-family:Consolas">...</span></p> </td> </tr> </tbody> </table> <p><strong>参数说明</strong>:</p> <table border="1" cellpadding="0" cellspacing="0"> <tbody> <tr> <td style="background-color:#ededed; vertical-align:top"> <p><strong>参数</strong></p> </td> <td style="background-color:#ededed; vertical-align:top"> <p><strong>是否必选</strong></p> </td> <td style="background-color:#ededed; vertical-align:top"> <p><strong>类型</strong></p> </td> <td style="background-color:#ededed; vertical-align:top"> <p><strong>说明</strong></p> </td> </tr> <tr> <td style="vertical-align:top"> <p>x-signature-algorithm</p> </td> <td style="vertical-align:top"> <p>是</p> </td> <td style="vertical-align:top"> <p>String</p> </td> <td> <p>API网关支持的签名算法:</p> <ul> <li>H_MAC_SHA1</li> <li>H_MAC_SHA256</li> </ul> </td> </tr> </tbody> </table> <p><strong><span style="font-size:18px">&bull; 5&nbsp; x-path-match-type:匹配模式</span></strong></p> <p><strong>含义</strong><strong>:</strong><a href="https://swagger.io/specification/v2/#operationObject" target="_blank">Operation Object</a>&nbsp;属性扩展,表示该API的路径匹配模式。</p> <p><strong>示例:</strong></p> <table border="0" cellpadding="0" cellspacing="0"> <tbody> <tr> <td style="background-color:#f7f8fa; vertical-align:top"> <p><span style="font-family:Consolas">...</span></p> <p><span style="font-family:Consolas">paths:</span></p> <p><span style="font-family:Consolas">&nbsp; &#39;/path&#39;:</span></p> <p><span style="font-family:Consolas">&nbsp;&nbsp;&nbsp; get:</span></p> <p><span style="font-family:Consolas">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; x-path-match-type: PREFIX</span></p> <p><span style="font-family:Consolas">...</span></p> </td> </tr> </tbody> </table> <p><strong>参数说明</strong>:</p> <table border="1" cellpadding="0" cellspacing="0"> <tbody> <tr> <td style="background-color:#ededed; vertical-align:top"> <p><strong>参数</strong></p> </td> <td style="background-color:#ededed; vertical-align:top"> <p><strong>是否必选</strong></p> </td> <td style="background-color:#ededed; vertical-align:top"> <p><strong>类型</strong></p> </td> <td style="background-color:#ededed; vertical-align:top"> <p><strong>说明</strong></p> </td> </tr> <tr> <td> <p>x-path-match-type</p> </td> <td style="vertical-align:top"> <p>是</p> </td> <td style="vertical-align:top"> <p>String</p> </td> <td> <p>请求路径的匹配模式,目前支持:</p> <p>&bull;&nbsp; &nbsp;NORMAL:完整路径匹配,调用的请求路径需要与创建API时设置的请求PATH完全一致。</p> <p>&bull;&nbsp; &nbsp;PREFIX:前缀路径匹配,调用的请求路径以创建API时设置的请求PATH为前缀<strong>。</strong></p> <p>&nbsp; &nbsp; 例如:/getUserInfo/test/AAA或/getUserInfo/test/BBB均可匹配到/getUserInfo/test,但不会匹配/getUserInfotest。</p> </td> </tr> </tbody> </table> <p><span style="font-size:18px"><strong>&bull; 6&nbsp; x-request-cors:跨域</strong></span></p> <p><strong>含义:</strong><a href="https://swagger.io/specification/v2/#operationObject" target="_blank">Operation Object</a>&nbsp;属性扩展,表示该API是否支持跨域。</p> <p><strong>示例:</strong></p> <table border="0" cellpadding="0" cellspacing="0"> <tbody> <tr> <td style="background-color:#f7f8fa; vertical-align:top"> <p><span style="font-family:Consolas">...</span></p> <p><span style="font-family:Consolas">paths:</span></p> <p><span style="font-family:Consolas">&nbsp; &#39;/path&#39;:</span></p> <p><span style="font-family:Consolas">&nbsp;&nbsp;&nbsp;&nbsp; get:</span></p> <p><span style="font-family:Consolas">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; x-request-cors: true</span></p> <p><span style="font-family:Consolas">...</span></p> </td> </tr> </tbody> </table> <p><strong>参数说明</strong>:</p> <table border="1" cellpadding="0" cellspacing="0"> <tbody> <tr> <td style="background-color:#ededed; vertical-align:top"> <p><strong>参数</strong></p> </td> <td style="background-color:#ededed; vertical-align:top"> <p><strong>是否必选</strong></p> </td> <td style="background-color:#ededed; vertical-align:top"> <p><strong>类型</strong></p> </td> <td style="background-color:#ededed; vertical-align:top"> <p><strong>说明</strong></p> </td> </tr> <tr> <td> <p>x-request-cors</p> </td> <td style="vertical-align:top"> <p>否</p> </td> <td style="vertical-align:top"> <p>String</p> </td> <td> <p>是否支持跨域,默认情况是false:</p> <p>&bull;&nbsp;&nbsp; true:支持跨域</p> <p>&bull;&nbsp;&nbsp; false:不支持跨域</p> </td> </tr> </tbody> </table> <p><span style="font-size:18px"><strong>&bull; 7&nbsp; x-body-desc:请求体描述</strong></span></p> <p><strong>含义</strong><strong>:</strong><a href="https://swagger.io/specification/v2/#operationObject" target="_blank">Operation Object</a>&nbsp;属性扩展,用于描述API请求体内容。</p> <p><strong>示例</strong>:</p> <table border="0" cellpadding="0" cellspacing="0"> <tbody> <tr> <td style="background-color:#f7f8fa; vertical-align:top"> <p><span style="font-family:Consolas">...</span></p> <p><span style="font-family:Consolas">paths:</span></p> <p><span style="font-family:Consolas">&nbsp; &#39;/path&#39;:</span></p> <p><span style="font-family:Consolas">&nbsp;&nbsp;&nbsp;&nbsp; post:</span></p> <p><span style="font-family:Consolas">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; x-body-desc: The description of request body</span></p> <p><span style="font-family:Consolas">...</span></p> </td> </tr> </tbody> </table> <p><strong>参数说明</strong>:</p> <table border="1" cellpadding="0" cellspacing="0"> <tbody> <tr> <td style="background-color:#ededed; vertical-align:top"> <p><strong>参数</strong></p> </td> <td style="background-color:#ededed; vertical-align:top"> <p><strong>是否必选</strong></p> </td> <td style="background-color:#ededed; vertical-align:top"> <p><strong>类型</strong></p> </td> <td style="background-color:#ededed; vertical-align:top"> <p><strong>说明</strong></p> </td> </tr> <tr> <td> <p>x-body-desc</p> </td> <td style="vertical-align:top"> <p>否</p> </td> <td style="vertical-align:top"> <p>String</p> </td> <td> <p>请求体描述。</p> <p>请求方法可以是POST、PUT、PATCH、ANY等。</p> </td> </tr> </tbody> </table> <p>&nbsp;<span style="font-size:18px"><strong>&bull; 8&nbsp; <a name="id_01">x-example</a>:入参定义示例</strong></span></p> <p><strong>含义</strong><strong>:</strong><a href="https://swagger.io/specification/v2/#parameterObject" target="_blank">Parameter Object</a>&nbsp;属性扩展,用于描述API请求参数的示例。</p> <p><strong>示例</strong>:</p> <table border="0" cellpadding="0" cellspacing="0"> <tbody> <tr> <td style="background-color:#f7f8fa; vertical-align:top"> <p><span style="font-family:Consolas">...</span></p> <p><span style="font-family:Consolas">paths:</span></p> <p><span style="font-family:Consolas">&nbsp; &#39;/path&#39;:</span></p> <p><span style="font-family:Consolas">&nbsp;&nbsp;&nbsp;&nbsp; get:</span></p> <p><span style="font-family:Consolas">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; parameters:</span></p> <p><span style="font-family:Consolas">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; - {description: request param in header, in: header, name: reqHeader, required: false,</span></p> <p><span style="font-family:Consolas">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; default: pingan, type: string, x-example: apigateway}</span></p> <p><span style="font-family:Consolas">...</span></p> </td> </tr> </tbody> </table> <p><strong>参数说明</strong>:</p> <table border="1" cellpadding="0" cellspacing="0"> <tbody> <tr> <td style="background-color:#ededed; vertical-align:top"> <p><strong>参数</strong></p> </td> <td style="background-color:#ededed; vertical-align:top"> <p><strong>是否必选</strong></p> </td> <td style="background-color:#ededed; vertical-align:top"> <p><strong>类型</strong></p> </td> <td style="background-color:#ededed; vertical-align:top"> <p><strong>说明</strong></p> </td> </tr> <tr> <td> <p>description</p> </td> <td> <p>否</p> </td> <td> <p>string</p> </td> <td> <p>参数的相关描述信息。</p> </td> </tr> <tr> <td> <p>name</p> </td> <td> <p>是</p> </td> <td> <p>string</p> </td> <td> <p>参数的名称。</p> </td> </tr> <tr> <td> <p>in</p> </td> <td> <p>是</p> </td> <td> <p>string</p> </td> <td> <p>参数的位置,支持:path、query、header。</p> </td> </tr> <tr> <td> <p>type</p> </td> <td> <p>是</p> </td> <td> <p>string</p> </td> <td> <p>参数的属性值类型,支持:string、integer、number、boolean。</p> </td> </tr> <tr> <td> <p>required</p> </td> <td> <p>是</p> </td> <td> <p>string</p> </td> <td> <p>参数的属性值是否必填:</p> <p>&bull;&nbsp; true:必填</p> <p>&bull;&nbsp; false:可选</p> </td> </tr> <tr> <td> <p>default</p> </td> <td> <p>否</p> </td> <td> <p>string</p> </td> <td> <p>参数属性值的默认情况,当required为true时需要设置。</p> </td> </tr> <tr> <td> <p>x-example</p> </td> <td> <p>否</p> </td> <td> <p>string</p> </td> <td> <p>参数的属性值示例。</p> </td> </tr> </tbody> </table> <p><span style="font-size:18px"><strong>&bull; 9&nbsp; x-backend-parameters:后端服务参数</strong></span></p> <p><strong>含义</strong><strong>:</strong><a href="https://swagger.io/specification/v2/#parameterObject" target="_blank">Parameter Object</a> 属性扩展,用于指定API入参定义与后端服务参数的映射关系。</p> <p><strong>.yaml</strong><strong>文件格式示例</strong>:</p> <table border="0" cellpadding="0" cellspacing="0"> <tbody> <tr> <td style="background-color:#f7f8fa; vertical-align:top"> <p><span style="font-family:Consolas">...</span></p> <p><span style="font-family:Consolas">&nbsp; parameters:</span></p> <p><span style="font-family:Consolas">&nbsp; - name: reqPath</span></p> <p><span style="font-family:Consolas">&nbsp;&nbsp;&nbsp; in: path</span></p> <p><span style="font-family:Consolas">&nbsp;&nbsp;&nbsp; required: true</span></p> <p><span style="font-family:Consolas">&nbsp;&nbsp;&nbsp; type: string</span></p> <p><span style="font-family:Consolas">&nbsp;&nbsp;&nbsp; x-backend-parameters:</span></p> <p><span style="font-family:Consolas">&nbsp;&nbsp;&nbsp; - {location: path, name: backPath}</span></p> <p><span style="font-family:Consolas">&nbsp;&nbsp;&nbsp; x-example: apigateway</span></p> <p><span style="font-family:Consolas">&nbsp;&nbsp;&nbsp; description: request param in path</span></p> <p><span style="font-family:Consolas">...</span></p> </td> </tr> </tbody> </table> <p><strong>.json</strong><strong>文件格式示例</strong>:</p> <table border="0" cellpadding="0" cellspacing="0"> <tbody> <tr> <td style="background-color:#f7f8fa; vertical-align:top"> <p><span style="font-family:Consolas">...</span></p> <p><span style="font-family:Consolas">&nbsp; &quot;parameters&quot;:[</span></p> <p><span style="font-family:Consolas">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; {</span></p> <p><span style="font-family:Consolas">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; &quot;name&quot;:&quot;reqPath&quot;,</span></p> <p><span style="font-family:Consolas">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; &quot;in&quot;:&quot;path&quot;,</span></p> <p><span style="font-family:Consolas">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; &quot;required&quot;:true,</span></p> <p><span style="font-family:Consolas">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; &quot;type&quot;:&quot;string&quot;,</span></p> <p><span style="font-family:Consolas">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; &quot;description&quot;:&quot;request param in path&quot;,</span></p> <p><span style="font-family:Consolas">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; &quot;x-backend-parameters&quot;:[</span></p> <p><span style="font-family:Consolas">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; {</span></p> <p><span style="font-family:Consolas">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; &quot;location&quot;:&quot;path&quot;,</span></p> <p><span style="font-family:Consolas">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; &quot;name&quot;:&quot;backPath&quot;</span></p> <p><span style="font-family:Consolas">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; }</span></p> <p><span style="font-family:Consolas">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; ],</span></p> <p><span style="font-family:Consolas">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; &quot;x-example&quot;:&quot;apigateway&quot;</span></p> <p><span style="font-family:Consolas">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; }</span></p> <p><span style="font-family:Consolas">&nbsp; ],</span></p> <p><span style="font-family:Consolas">...</span></p> </td> </tr> </tbody> </table> <p><strong>参数说明</strong>:</p> <p><!--[if gte mso 9]><xml> <o:OLEObject Type="Embed" ProgID="PBrush" ShapeID="_x0000_i1025" DrawAspect="Content" ObjectID="_1633961843"> </o:OLEObject> </xml><![endif]--><img src="https://pcp-portal-sca.obs-cn-shenzhen.pinganyun.com/pcp-portal-sca/20193010165904-13a8654e9b96.png" style="height:26px; margin:0px; width:65px" />:后端服务参数依赖于入参参数,当定义有入参参数时,可将该参数映射为后端参数(入参定义,可参考<a href="#id_01" target="_blank">x-example</a>)</p> <table border="1" cellpadding="0" cellspacing="0"> <tbody> <tr> <td style="background-color:#ededed; vertical-align:top"> <p><strong>参数</strong></p> </td> <td style="background-color:#ededed; vertical-align:top"> <p><strong>是否必选</strong></p> </td> <td style="background-color:#ededed; vertical-align:top"> <p><strong>类型</strong></p> </td> <td style="background-color:#ededed; vertical-align:top"> <p><strong>说明</strong></p> </td> </tr> <tr> <td> <p>location</p> </td> <td> <p>是</p> </td> <td> <p>string</p> </td> <td> <p>后端服务参数的位置,目前支持:path、query、header。</p> </td> </tr> <tr> <td> <p>name</p> </td> <td> <p>是</p> </td> <td> <p>string</p> </td> <td> <p>后端服务参数的名称。</p> </td> </tr> </tbody> </table> <p><span style="font-size:18px"><strong>&bull; 10&nbsp; x-backend:后端服务类型</strong></span></p> <p><strong>含义</strong><strong>:</strong><a href="https://swagger.io/specification/v2/#operationObject" target="_blank">Operation Object</a>&nbsp;属性扩展,用于描述API后端服务类型。<strong> </strong></p> <p><strong>参数说明</strong>:</p> <table border="1" cellpadding="0" cellspacing="0"> <tbody> <tr> <td style="background-color:#ededed; vertical-align:top"> <p><strong>参数</strong></p> </td> <td style="background-color:#ededed; vertical-align:top"> <p><strong>是否必选</strong></p> </td> <td style="background-color:#ededed; vertical-align:top"> <p><strong>类型</strong></p> </td> <td style="background-color:#ededed; vertical-align:top"> <p><strong>说明</strong></p> </td> </tr> <tr> <td> <p>x-backend</p> </td> <td style="vertical-align:top"> <p>是</p> </td> <td style="vertical-align:top"> <p>string</p> </td> <td> <p>后端服务类型,目前支持:HTTP/ HTTPS、MOCK</p> </td> </tr> </tbody> </table> <p><span style="font-size:18px"><strong>&bull; 10.1&nbsp; HTTP后端服务类型</strong></span></p> <p><strong>含义</strong><strong>:后端服务类型</strong>为<strong>HTTP/ HTTPS</strong>时<strong>,</strong>API网关可转发HTTP/HTTPS协议的请求<strong>。</strong></p> <p><strong>示例</strong>:</p> <table border="0" cellpadding="0" cellspacing="0"> <tbody> <tr> <td style="background-color:#f7f8fa; vertical-align:top"> <p><span style="font-family:Consolas">...</span></p> <p><span style="font-family:Consolas">x-backend:</span></p> <p><span style="font-family:Consolas">- {address:&#39;http://10.10.10.10:8888&#39;,method:ANY,path:&#39;/back/{backPath}/{consPath}/{sysPath}&#39;,timeout: 6000, type: HTTP}</span></p> <p><span style="font-family:Consolas">...</span></p> </td> </tr> </tbody> </table> <p><strong>参数说明</strong>:</p> <table border="1" cellpadding="0" cellspacing="0"> <tbody> <tr> <td style="background-color:#ededed; vertical-align:top"> <p><strong>参数</strong></p> </td> <td style="background-color:#ededed; vertical-align:top"> <p><strong>是否必选</strong></p> </td> <td style="background-color:#ededed; vertical-align:top"> <p><strong>类型</strong></p> </td> <td style="background-color:#ededed; vertical-align:top"> <p><strong>说明</strong></p> </td> </tr> <tr> <td> <p>type</p> </td> <td> <p>是</p> </td> <td> <p>string</p> </td> <td> <p>后端服务类型:HTTP。</p> </td> </tr> <tr> <td> <p>address</p> </td> <td> <p>是</p> </td> <td> <p>string</p> </td> <td> <p>后端服务的地址。</p> </td> </tr> <tr> <td> <p>path</p> </td> <td> <p>是</p> </td> <td> <p>string</p> </td> <td> <p>后端服务的请求路径。</p> </td> </tr> <tr> <td> <p>method</p> </td> <td> <p>是</p> </td> <td> <p>string</p> </td> <td> <p>后端服务的请求方法:目前支持:GET、POST、PUT、DELETE、HEAD、OPTIONS、PATCH、ANY。</p> </td> </tr> <tr> <td> <p>timeout</p> </td> <td> <p>是</p> </td> <td> <p>integer</p> </td> <td> <p>后端请求超时阈值,取值范围:1-600000ms,默认情况是5000ms。</p> </td> </tr> <tr> <td> <p>x-constant-parameters</p> </td> <td> <p>否</p> </td> <td> <p>Constatnt Object</p> </td> <td> <p>常量参数,可参考<a href="#id_02" target="_blank">x-constant-parameters</a>。</p> </td> </tr> <tr> <td> <p>x-system-parameters</p> </td> <td> <p>否</p> </td> <td> <p>System Object</p> </td> <td> <p>系统参数,可参考<a href="#id_03" target="_blank">x-system-parameters</a>。</p> </td> </tr> </tbody> </table> <p><span style="font-size:18px"><strong>&bull; 10.2&nbsp; MOCK后端服务类型</strong></span></p> <p><strong>含义</strong><strong>:后端服务类型</strong>为<strong>MOCK</strong>时,主要用于API的调试环境,不调用后端服务,直接返回设置的结果给API调用方<strong>。</strong></p> <p><strong>示例</strong>:</p> <table border="0" cellpadding="0" cellspacing="0"> <tbody> <tr> <td style="background-color:#f7f8fa; vertical-align:top"> <p><span style="font-family:Consolas">...&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</span></p> <p><span style="font-family:Consolas">&nbsp;x-backend:</span></p> <p><span style="font-family:Consolas">&nbsp;&nbsp; mockHeaders:</span></p> <p><span style="font-family:Consolas">&nbsp;&nbsp; - {name: PA001, value: 平安集团}</span></p> <p><span style="font-family:Consolas">&nbsp;&nbsp; - {name: PA011, value: 平安科技}</span></p> <p><span style="font-family:Consolas">&nbsp;&nbsp; mockResult: mock result</span></p> <p><span style="font-family:Consolas">&nbsp;&nbsp; type: MOCK</span></p> <p><span style="font-family:Consolas">...</span></p> </td> </tr> </tbody> </table> <p><strong>参数说明</strong>:</p> <table border="1" cellpadding="0" cellspacing="0"> <tbody> <tr> <td style="background-color:#ededed; vertical-align:top"> <p><strong>参数</strong></p> </td> <td style="background-color:#ededed; vertical-align:top"> <p><strong>是否必选</strong></p> </td> <td style="background-color:#ededed; vertical-align:top"> <p><strong>类型</strong></p> </td> <td style="background-color:#ededed; vertical-align:top"> <p><strong>说明</strong></p> </td> </tr> <tr> <td> <p>type</p> </td> <td> <p>是</p> </td> <td> <p>string</p> </td> <td> <p>后端服务类型:MOCK。</p> </td> </tr> <tr> <td> <p>mockResult</p> </td> <td> <p>是</p> </td> <td> <p>string</p> </td> <td> <p>Mock返回结果。</p> </td> </tr> <tr> <td> <p>mockHeaders</p> </td> <td> <p>否</p> </td> <td> <p>MockHeader Object</p> </td> <td> <p>Mock响应头,可参考mockHeaders。</p> </td> </tr> </tbody> </table> <p><span style="font-size:18px"><strong>&bull; 10.2.1&nbsp; mockHeaders:Mock响应头参数</strong></span></p> <p><strong>含义</strong><strong>:</strong>MOCK响应头数据定义。</p> <p><strong>示例</strong>:</p> <table border="0" cellpadding="0" cellspacing="0"> <tbody> <tr> <td style="background-color:#f7f8fa; vertical-align:top"> <p><span style="font-family:Consolas">...</span></p> <p><span style="font-family:Consolas">&nbsp; mockHeaders:</span></p> <p><span style="font-family:Consolas">&nbsp; - {name: PA011, value: 平安科技}</span></p> <p><span style="font-family:Consolas">...</span></p> </td> </tr> </tbody> </table> <p><strong>参数说明</strong>:</p> <table border="1" cellpadding="0" cellspacing="0"> <tbody> <tr> <td style="background-color:#ededed; vertical-align:top"> <p><strong>参数</strong></p> </td> <td style="background-color:#ededed; vertical-align:top"> <p><strong>是否必选</strong></p> </td> <td style="background-color:#ededed; vertical-align:top"> <p><strong>类型</strong></p> </td> <td style="background-color:#ededed; vertical-align:top"> <p><strong>说明</strong></p> </td> </tr> <tr> <td> <p>name</p> </td> <td> <p>是</p> </td> <td> <p>string</p> </td> <td> <p>MOCK响应头的参数名称。</p> </td> </tr> <tr> <td> <p>value</p> </td> <td> <p>是</p> </td> <td> <p>string</p> </td> <td> <p>MOCK响应头的参数取值。</p> </td> </tr> </tbody> </table> <p><span style="font-size:18px"><strong>&bull; 11&nbsp; <a name="id_02">x-constant-parameters</a>:常量参数</strong></span></p> <p><strong>含义</strong><strong>:</strong><a href="https://swagger.io/specification/v2/#parameterObject" target="_blank">Parameter Object<strong> </strong></a>属性扩展,在后端服务类型为HTTP时,可设置API网关的常量参数。</p> <p><strong>示例</strong>:</p> <table border="0" cellpadding="0" cellspacing="0"> <tbody> <tr> <td style="background-color:#f7f8fa; vertical-align:top"> <p><span style="font-family:Consolas">...</span></p> <p><span style="font-family:Consolas">&nbsp; x-constant-parameters:</span></p> <p><span style="font-family:Consolas">&nbsp; - {name: conPa, location: query, value: apigateway, description: The constant parameter in backend}</span></p> <p><span style="font-family:Consolas">...</span></p> </td> </tr> </tbody> </table> <p><strong>参数说明</strong>:</p> <table border="1" cellpadding="0" cellspacing="0"> <tbody> <tr> <td style="background-color:#ededed; vertical-align:top"> <p><strong>参数</strong></p> </td> <td style="background-color:#ededed; vertical-align:top"> <p><strong>是否必选</strong></p> </td> <td style="background-color:#ededed; vertical-align:top"> <p><strong>类型</strong></p> </td> <td style="background-color:#ededed; vertical-align:top"> <p><strong>说明</strong></p> </td> </tr> <tr> <td> <p>name</p> </td> <td> <p>是</p> </td> <td> <p>string</p> </td> <td> <p>常量参数的名称。</p> </td> </tr> <tr> <td> <p>value</p> </td> <td> <p>是</p> </td> <td> <p>string</p> </td> <td> <p>常量参数的取值。</p> </td> </tr> <tr> <td> <p>location</p> </td> <td> <p>是</p> </td> <td> <p>string</p> </td> <td> <p>常量参数的位置,目前支持:path、query、header。</p> </td> </tr> <tr> <td> <p>description</p> </td> <td> <p>否</p> </td> <td> <p>string</p> </td> <td> <p>常量参数的相关描述信息。</p> </td> </tr> </tbody> </table> <p><span style="font-size:18px"><strong>&bull; 12&nbsp; <a name="id_03">x-system-parameters</a>:系统参数</strong></span></p> <p><strong>含义</strong><strong>:</strong><a href="https://swagger.io/specification/v2/#parameterObject" target="_blank">Parameter Object</a><strong> </strong>属性扩展,在后端服务类型为HTTP时,可设置API网关的系统参数。</p> <p><strong>示例</strong>:</p> <table border="0" cellpadding="0" cellspacing="0"> <tbody> <tr> <td style="background-color:#f7f8fa; vertical-align:top"> <p><span style="font-family:Consolas">...</span></p> <p><span style="font-family:Consolas">&nbsp; x-system-parameters:</span></p> <p><span style="font-family:Consolas">&nbsp; - {name: sysPa, location: query, value: PA-AG-RequestId}</span></p> <p><span style="font-family:Consolas">...</span></p> </td> </tr> </tbody> </table> <p><strong>参数说明</strong>:</p> <table border="1" cellpadding="0" cellspacing="0"> <tbody> <tr> <td style="vertical-align:top"> <p><strong>参数</strong></p> </td> <td style="vertical-align:top"> <p><strong>是否必选</strong></p> </td> <td style="vertical-align:top"> <p><strong>类型</strong></p> </td> <td style="vertical-align:top"> <p><strong>说明</strong></p> </td> </tr> <tr> <td> <p>name</p> </td> <td> <p>是</p> </td> <td> <p>string</p> </td> <td> <p>系统参数的名称。</p> </td> </tr> <tr> <td> <p>value</p> </td> <td> <p>是</p> </td> <td> <p>string</p> </td> <td> <p>系统参数的取值:目前支持:</p> <ul> <li>PA-AG-RequestId:客户端发送或API网关生成的API请求标识ID。</li> <li>PA-AG-Timestamp:客户端发送API请求时的时间戳。</li> <li>PA-AG-Env:客户端调用API的环境,默认情况是线上环境release。</li> <li>PA-AG-ClientIP:客户端的IP地址。</li> <li>PA-AG-AppId:客户端使用的应用(APP)的标识ID。</li> <li>PA-AG-GroupId:客户端调用的API所属分组的标识ID。</li> <li>PA-AG-UserId:客户端使用的应用(APP)的所属账户ID(TenantUUID)。</li> <li>PA-AG-Gateway-ChargeMode:调用API时付费模式。</li> <li>PA-AG-Gateway-Timestamp:API网关接受并处理API请求的时间戳。</li> </ul> </td> </tr> <tr> <td> <p>location</p> </td> <td> <p>是</p> </td> <td> <p>string</p> </td> <td> <p>系统参数的位置,目前支持:path、query、header。</p> </td> </tr> </tbody> </table> <p><span style="font-size:18px"><strong>&bull; 13&nbsp; x-response-content-type:返回结果的内容类型</strong></span></p> <p><strong>含义</strong><strong>:</strong><a href="https://swagger.io/specification/v2/#operationObject" target="_blank">Operation Object</a>&nbsp;属性扩展,用于描述返回Content-type类型。</p> <p><strong>示例</strong>:</p> <table border="0" cellpadding="0" cellspacing="0"> <tbody> <tr> <td style="background-color:#f7f8fa; vertical-align:top"> <p><span style="font-family:Consolas">...</span></p> <p><span style="font-family:Consolas">paths:</span></p> <p><span style="font-family:Consolas">&nbsp; &#39;/path&#39;:</span></p> <p><span style="font-family:Consolas">&nbsp;&nbsp;&nbsp; get:</span></p> <p><span style="font-family:Consolas">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; x-response-content-type: application/xml;charset=utf-8</span></p> <p><span style="font-family:Consolas">...</span></p> </td> </tr> </tbody> </table> <p><strong>参数说明</strong>:</p> <table border="1" cellpadding="0" cellspacing="0"> <tbody> <tr> <td style="background-color:#ededed; vertical-align:top"> <p><strong>参数</strong></p> </td> <td style="background-color:#ededed; vertical-align:top"> <p><strong>是否必选</strong></p> </td> <td style="background-color:#ededed; vertical-align:top"> <p><strong>类型</strong></p> </td> <td style="background-color:#ededed; vertical-align:top"> <p><strong>说明</strong></p> </td> </tr> <tr> <td> <p>x-response-content-type</p> </td> <td> <p>是</p> </td> <td> <p>string</p> </td> <td> <p>调用API返回结果的内容类型,目前支持:</p> <ul> <li>application/json;charset=utf-8:JSON格式。</li> <li>text/plain;charset=utf-8:纯文本格式。</li> <li>application/octet-stream;charset=utf-8:二进制流格式。</li> <li>application/xml;charset=utf-8:XML解析格式。</li> <li>text/html;charset=utf-8:HTML解析格式。</li> <li>passthrough:透传Content-type。</li> </ul> </td> </tr> </tbody> </table> <p><span style="font-size:18px"><strong>&bull; 14&nbsp; x-response-success-result:成功的返回结果</strong></span></p> <p><strong>含义</strong><strong>:</strong><a href="https://swagger.io/specification/v2/#operationObject" target="_blank">Operation Object</a>&nbsp;属性扩展,用于描述调用API成功时的返回结果。</p> <p><strong>示例</strong>:</p> <table border="0" cellpadding="0" cellspacing="0"> <tbody> <tr> <td style="background-color:#f7f8fa; vertical-align:top"> <p><span style="font-family:Consolas">...</span></p> <p><span style="font-family:Consolas">paths:</span></p> <p><span style="font-family:Consolas">&nbsp; &#39;/path&#39;:</span></p> <p><span style="font-family:Consolas">&nbsp;&nbsp;&nbsp; get:</span></p> <p><span style="font-family:Consolas">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; x-response-success-result: success</span></p> <p><span style="font-family:Consolas">...</span></p> </td> </tr> </tbody> </table> <p><strong>参数说明</strong>:</p> <table border="1" cellpadding="0" cellspacing="0"> <tbody> <tr> <td style="background-color:#ededed; vertical-align:top"> <p><strong>参数</strong></p> </td> <td style="background-color:#ededed; vertical-align:top"> <p><strong>是否必选</strong></p> </td> <td style="background-color:#ededed; vertical-align:top"> <p><strong>类型</strong></p> </td> <td style="background-color:#ededed; vertical-align:top"> <p><strong>说明</strong></p> </td> </tr> <tr> <td> <p>x-response-success-result</p> </td> <td> <p>是</p> </td> <td> <p>string</p> </td> <td> <p>调用API成功,返回的响应结果。</p> </td> </tr> </tbody> </table> <p><span style="font-size:18px"><strong>&bull; 15&nbsp; x-response-failure-result:失败的返回结果</strong></span></p> <p><strong>含义</strong><strong>:</strong><a href="https://swagger.io/specification/v2/#operationObject" target="_blank">Operation Object </a>属性扩展,用于描述调用API失败时的返回结果。</p> <p><strong>示例</strong>:</p> <table border="0" cellpadding="0" cellspacing="0"> <tbody> <tr> <td style="background-color:#f7f8fa; vertical-align:top"> <p><span style="font-family:Consolas">...</span></p> <p><span style="font-family:Consolas">paths:</span></p> <p><span style="font-family:Consolas">&nbsp; &#39;/path&#39;:</span></p> <p><span style="font-family:Consolas">&nbsp;&nbsp;&nbsp; get:</span></p> <p><span style="font-family:Consolas">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; x-response-failure-result: error</span></p> <p><span style="font-family:Consolas">...</span></p> </td> </tr> </tbody> </table> <p><strong>参数说明</strong>:</p> <table border="1" cellpadding="0" cellspacing="0"> <tbody> <tr> <td style="background-color:#ededed; vertical-align:top"> <p><strong>参数</strong></p> </td> <td style="background-color:#ededed; vertical-align:top"> <p><strong>是否必选</strong></p> </td> <td style="background-color:#ededed; vertical-align:top"> <p><strong>类型</strong></p> </td> <td style="background-color:#ededed; vertical-align:top"> <p><strong>说明</strong></p> </td> </tr> <tr> <td> <p>x-response-failure-result</p> </td> <td> <p>是</p> </td> <td> <p>string</p> </td> <td> <p>调用API失败,返回的响应结果。</p> </td> </tr> </tbody> </table> <p><span style="font-size:18px"><strong>&bull; 16&nbsp; x-description:错误码</strong></span></p> <p><strong>含义</strong><strong>:</strong><a href="https://swagger.io/specification/v2/#operationObject" target="_blank">Operation Object</a>&nbsp;属性扩展,用于描述调用API出错时的错误信息。</p> <p>示例:</p> <table border="0" cellpadding="0" cellspacing="0"> <tbody> <tr> <td style="background-color:#f7f8fa; vertical-align:top"> <p><span style="font-family:Consolas">...</span></p> <p><span style="font-family:Consolas">paths:</span></p> <p><span style="font-family:Consolas">&nbsp; &#39;/path&#39;:</span></p> <p><span style="font-family:Consolas">&nbsp;&nbsp;&nbsp; get:</span></p> <p><span style="font-family:Consolas">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; responses:</span></p> <p><span style="font-family:Consolas">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; &#39;200&#39;: {description: success, x-description: &#39;success&#39;}</span></p> <p><span style="font-family:Consolas">...</span></p> </td> </tr> </tbody> </table> <p><strong>参数说明</strong>:</p> <table border="1" cellpadding="0" cellspacing="0"> <tbody> <tr> <td style="background-color:#ededed; vertical-align:top"> <p><strong>参数</strong></p> </td> <td style="background-color:#ededed; vertical-align:top"> <p><strong>是否必选</strong></p> </td> <td style="background-color:#ededed; vertical-align:top"> <p><strong>类型</strong></p> </td> <td style="background-color:#ededed; vertical-align:top"> <p><strong>说明</strong></p> </td> </tr> <tr> <td> <p>x-description</p> </td> <td> <p>否</p> </td> <td> <p>string</p> </td> <td> <p>调用API出错时的错误码,可作为排查报错信息的索引。</p> </td> </tr> </tbody> </table>
以上内容是否解决了您的问题?
请补全提交信息!
咨询·建议

电话咨询

400-151-8800

邮件咨询

cloud@pingan.com

在线客服

工单支持

解决云产品相关技术问题