如何将 Swagger 与 SpringDoc YAML 集成？

Question

I'm using Swagger to document my project.And I want generate the YAML doc from springdoc. But when I generate this YAML documentation the YAML dont have my Swagger doc coments. For example. I have one endpoint in my project:

@ApiOperation(value = "Return a list of Pix Wallets.", httpMethod = "POST", response = DResponse.class)
@PostMapping("/digital-wallet")
public ResponseEntity<DResponse> getDigitalWallets(@RequestBody PixDigitalWalletRequest pixDigitalWalletRequest) {
    return ResponseEntity.ok(pixService.getDigitalWallets(pixDigitalWalletRequest));
}

When I open my swagger doc I can see the correct documentation:

But... When I generate my YAML doc I don't see my comment (like: "Return a list of Pix Wallets.") in my YAML doc. For example:

paths:
   /api/pix/digital-wallet:
      post:
         tags:
         - pix-controller
  operationId: getDigitalWallets
  requestBody:
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/PixDigitalWalletRequest'
  responses:
    "200":
      description: default response
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/DResponse'

How can add my Swagger comments in my YAML doc?

Answer 1

You're facing the issue cause you're using Swagger 1.x annotation with Springdoc which relies on Swagger 2.x annotations.

Refactor your code as below to solve the issue

@Operation(summary = "Return a list of Pix Wallets.")
@ApiResponses(value = {
        // 201 as it's a POST method, ideally shoud have empty schema as @Schema(), but put the class name to suit your use-case
        @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))})
})
@PostMapping("/digital-wallet")
public ResponseEntity<DResponse> getDigitalWallets(@RequestBody PixDigitalWalletRequest pixDigitalWalletRequest) {
    return ResponseEntity.ok(pixService.getDigitalWallets(pixDigitalWalletRequest));
}

Refer to the Migrating from Springfox - Springdoc page for a detailed list of all the annotations and other migration changes.