SpringDoc应用程序文档。yaml不要表现出狂妄自大的样子医生

Question

我有一个夸夸其谈的API。endpoint示例：

@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文档时，这个描述不起作用。我看不到endpoint的描述（返回Pix事务列表）在我的yaml文档中：

/api/pix/transactions:
post:
  tags:
  - pix-controller
  operationId: getTransactions
  requestBody:
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/PixTransactionRequest'

Answer 1

问题是因为您在Springdoc中使用了Swagger 1. x注释，而支持的Swagger规范是Swagger 2. x（又名OpenAPI规范）

对于此问题的解决方案，请使用@操作注释来获得预期的输出。

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

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

如果endpoint可以返回超过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))})
})

并且没有替代的http方法="POST"的@Api操作。Swagger 2. x通过放置在方法上的请求注释的类型推断操作的类型，即@PostMap将给出POST请求等等。当您使用@刚需映射指定请求方法的类型时，此规则仍然有效。