SpringDoc app-doc.yaml不显示招摇的文档

Question

我有一个挥霍的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'

Answer 1

问题是因为您在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", content = {@Content(mediaType = "application/json", schema = @Schema(DResponse.class))}),
        @ApiResponse(responseCode = "500", description = "Internal Server Error", content = {@Content(mediaType = "application/json", schema = @Schema(implementation = MyErrorResponse.class))})
})

httpMethod = "POST"中的@ApiOperation别无选择。 Swagger 2.x通过放置在方法上的请求注释的类型来推断操作的类型，即@PostMapping将发出POST请求，依此类推。当您使用@RequestMapping指定请求方法的类型时，该规则仍然有效。