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

问题是因为您将 Swagger 1.x 注释 @ApiOperation 与 Springdoc 一起使用，而支持的 Swagger 规范是 Swagger 2.x（又名 OpenAPI 规范）

至于解决这个问题，使用@Operation注解得到预期的输出。

请注意，无法使用新注释指定返回类型。因此，要实现相同的功能，您需要重写您的 swagger 注释，如下所示

// 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))})

如果端点可以返回超过 1 个响应，请使用以下方法

@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 指定请求方法的类型时，此规则仍然有效。