如何将 Swagger 与 SpringDoc YAML 集成？答案

【问题标题】：How to integrate Swagger with SpringDoc YAML?如何将 Swagger 与 SpringDoc YAML 集成？
【发布时间】：2021-02-06 17:35:41
【问题描述】：

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

@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 文档时，我可以看到正确的文档：

但是...当我生成 YAML 文档时，我在 YAML 文档中看不到我的评论（例如：“返回 Pix 钱包列表。”）。例如：

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 cmets？

【问题讨论】：

究竟是如何生成 YAML 文件的？您也可以尝试将 YAML/JSON 文件从 Swagger UI 导出为 explained here。

标签： swagger swagger-ui springdoc springdoc-openui

【解决方案1】：

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

重构你的代码如下解决问题

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

有关所有注释和其他迁移更改的详细列表，请参阅 Migrating from Springfox - Springdoc 页面。

【讨论】：