SpringDoc app-doc.yaml не показывает документ чванства

Question

У меня есть API с чванством. Пример конечной точки:

       @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, это описание не работает. Я не вижу описания конечной точки (возвращает список транзакций Pix.) В моем yaml-документе:

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

Answer 1

Проблема в том, что вы используете аннотацию Swagger 1.x @ApiOperation с Springdoc, в то время как поддерживаемая спецификация Swagger - Swagger 2.x (также известная как спецификация OpenAPI)

Что касается решения этого, используйте @Operation аннотацию, чтобы получить ожидаемый результат.

Обратите внимание, что с помощью новой аннотации невозможно указать тип возвращаемого значения. Таким образом, для достижения той же функциональности вам нужно переписать аннотацию чванства, как показано ниже

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

Если конечная точка может вернуть более 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))})
})

И нет альтернативы httpMethod = "POST" из @ApiOperation. Swagger 2.x определяет тип операции по типу аннотации запроса, помещенной в метод, т. Е. @PostMappingдаст запрос POST и так далее. Это правило все еще сохраняется, когда вы используете @RequestMapping чтобы указать тип метода запроса.