如何将 Swagger 与 SpringDoc YAML 集成? [英] How to integrate Swagger with SpringDoc YAML?

问题描述

我正在使用 Swagger 来记录我的项目.我想从 springdoc 生成 YAML 文档.但是当我生成这个 YAML 文档时，YAML 没有我的 Swagger 文档注释.例如.我的项目中有一个端点:

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

当我打开我的 swagger 文档时，我可以看到正确的文档:

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

但是...当我生成我的 YAML 文档时，我在我的 YAML 文档中没有看到我的评论(例如:返回 Pix 钱包列表.").例如:

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'

如何在我的 YAML 文档中添加我的 Swagger 评论?

How can add my Swagger comments in my YAML doc?

推荐答案

您面临的问题是因为您将 Swagger 1.x 注释与依赖 Swagger 2.x 注释的 Springdoc 一起使用.

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

请参阅 从 Springfox 迁移 - Springdoc 页面以获取所有详细列表注释和其他迁移更改.

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

这篇关于如何将 Swagger 与 SpringDoc YAML 集成?的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！