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

У меня есть 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'

spring-boot swagger swagger-ui springdoc springdoc-openui
person lucas.iter    schedule 20.10.2020    source источник
comment
Вопрос основан на Как интегрировать Swagger с SpringDoc YAML.   -  person Debargha Roy    schedule 30.10.2020

Ответы (1)


arrow_upward
1
arrow_downward

Проблема заключается в том, что вы используете аннотацию 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 для указания типа метода запроса.

person Debargha Roy    schedule 30.10.2020
comment
ucas.iter, вы должны принять ответ. - person brianbro; 02.12.2020