SpringDoc app-doc.yaml don't show the swagger doc

Question

I have a API with swagger. Endpoint example:

@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));
}

My swagger page show me all the info correctly:

But when I tryed generate a yaml doc this description don't works. I dont see the description of the endpoint (Returns a list of Pix transactions.) in my yaml doc:

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

Answer 1

The issue is because you're using Swagger 1.x annotation @ApiOperation with Springdoc while the supported Swagger specification is Swagger 2.x (aka the OpenAPI Specification)

As for the solution to this, use the @Operation annotation to get the expected output.

Note that it's not possible to speicify the return type with the new annotation. Thus to achieve the same functionality you need to re-write your swagger annotation as below

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

If the endpoint can return more than 1 response, use the below approach

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

And there's no alternative for httpMethod = "POST" of the @ApiOperation. Swagger 2.x infers the type of operation by the type of request annotation placed on the method, i.e @PostMapping will give a POST request and so on. This rule still holds when you use @RequestMapping to specify the type of request method.