Jak zintegrować Swagger ze SpringDoc YAML?

Question

Używam Swaggera do dokumentowania mojego projektu i chcę wygenerować dokument YAML z springdoc. Ale kiedy generuję tę dokumentację YAML, YAML nie ma komentarzy do mojego dokumentu Swagger. Na przykład. Mam jeden punkt końcowy w moim projekcie:

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

Kiedy otwieram dokument ze swagger, widzę poprawną dokumentację:

Ale ... Kiedy generuję dokument YAML, nie widzę swojego komentarza (na przykład: „Zwróć listę portfeli Pix.”) W moim dokumencie YAML. Na przykład:

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'

Jak mogę dodać moje komentarze Swaggera w moim dokumencie YAML?

Answer 1

Masz do czynienia z problemem, ponieważ używasz adnotacji Swagger 1.x ze Springdoc, która opiera się na adnotacjach Swagger 2.x.

Aby rozwiązać problem, zmodyfikuj kod jak poniżej

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

Zobacz stronę Migracja ze Springfox - Springdoc, aby uzyskać szczegółową listę wszystkich adnotacji i innych zmian migracji.