¿Cómo integrar Swagger con SpringDoc YAML?

Question

Estoy usando Swagger para documentar mi proyecto y quiero generar el documento YAML desde springdoc. Pero cuando genero esta documentación YAML, el YAML no tiene mis comentarios sobre el documento Swagger. Por ejemplo. Tengo un punto final en mi proyecto:

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

Cuando abro mi documento swagger puedo ver la documentación correcta:

Pero ... Cuando genero mi documento YAML, no veo mi comentario (como: "Devolver una lista de Pix Wallets") en mi documento YAML. Por ejemplo:

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'

¿Cómo puedo agregar mis comentarios Swagger en mi documento YAML?

Answer 1

Se enfrenta al problema porque está utilizando la anotación Swagger 1.x con Springdoc, que se basa en las anotaciones Swagger 2.x.

Refactorice su código como se muestra a continuación para resolver el problema

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

Consulte la página Migración desde Springfox - Springdoc para obtener una lista detallada de todas las anotaciones y otros cambios de migración.