如何解决SpringDoc app-doc.yaml不显示招摇的文档
我有一个挥霍的API。端点示例:
@ApiOperation(value = "Returns a list of Pix transactions.",httpMethod = "POST",response = DResponse.class)
@PostMapping("/transactions")
public ResponseEntity<DResponse> getTransactions(@RequestBody PixTransactionRequest pixTransactionRequest) {
return ResponseEntity.ok(pixService.getTransactionsPix(pixTransactionRequest));
}
我的招摇页面向我正确显示了所有信息:
但是当我尝试生成Yaml文档时,此描述不起作用。我的Yaml文档中没有看到端点的描述(返回Pix事务列表。)
/api/pix/transactions:
post:
tags:
- pix-controller
operationId: getTransactions
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/PixTransactionRequest'
解决方法
问题是因为您在Springdoc中使用了Swagger 1.x注释@ApiOperation
,而支持的Swagger规范是Swagger 2.x(又称OpenAPI规范)
关于此问题的解决方案,请使用@Operation
批注以获取预期的输出。
请注意,无法使用新注释指定返回类型。因此,要实现相同的功能,您需要重新编写如下的招摇注解
// Describe the Operation
@Operation(summary = "Returns a list of Pix transactions.",description = "Any long description about the endpoint that you want")
// Describe the Response of the Operation. Use the below way if only 1 type of response will be returned by the endpoint
@ApiResponse(responseCode = "200",description = "OK",content = {@Content(mediaType = "application/json",schema = @Schema(DResponse.class))})
如果端点可以返回多个响应,请使用以下方法
@ApiResponses(value = {
@ApiResponse(responseCode = "201",description = "Created",schema = @Schema(DResponse.class))}),@ApiResponse(responseCode = "500",description = "Internal Server Error",schema = @Schema(implementation = MyErrorResponse.class))})
})
httpMethod = "POST"
中的@ApiOperation
别无选择。 Swagger 2.x通过放置在方法上的请求注释的类型来推断操作的类型,即@PostMapping
将发出POST请求,依此类推。当您使用@RequestMapping
指定请求方法的类型时,该规则仍然有效。
版权声明:本文内容由互联网用户自发贡献,该文观点与技术仅代表作者本人。本站仅提供信息存储空间服务,不拥有所有权,不承担相关法律责任。如发现本站有涉嫌侵权/违法违规的内容, 请发送邮件至 dio@foxmail.com 举报,一经查实,本站将立刻删除。