<dependency><groupId>org.springdoc</groupId><artifactId>springdoc-openapi-ui</artifactId><version>1.6.14</version>
</dependency>

springdoc-openapi-ui 是一個用于生成 OpenAPI 文檔的庫，它與 Swagger 的關系如下：

區別

1. OpenAPI 規范：

   • springdoc-openapi 是基于 OpenAPI 3.0 規范的實現，而 Swagger 2.0 是較早的版本。OpenAPI 3.0 提供了更豐富的功能和更好的支持。

2. 集成方式：

   • springdoc-openapi 提供了更簡單的集成方式，特別是在 Spring Boot 應用中。它可以自動掃描控制器和模型，并生成相應的 API 文檔。

3. 功能：

   • springdoc-openapi 支持 OpenAPI 3.0 的所有特性，包括更復雜的請求和響應模型、參數、請求體等。

方法、VO 和請求對象的配置

使用springdoc-openapi-ui時，配置方法和VO與swagger2有所不同，它基于JavaDoc注解和特定的OpenAPI注解。下面是針對springdoc-openapi-ui的完整配置方案：

1. VO類配置

import io.swagger.v3.oas.annotations.media.Schema;
import lombok.Data;import java.math.BigDecimal;
import java.time.LocalDateTime;@Data
@Schema(description = "招標數據明細響應對象")
public class TenderDetailVO {@Schema(description = "主鍵ID", example = "1001")private Long id;@Schema(description = "招標編號", example = "ZB2023001")private String tenderNo;@Schema(description = "項目名稱", example = "城市道路改造工程")private String projectName;@Schema(description = "招標單位", example = "市政建設有限公司")private String tenderUnit;@Schema(description = "招標方式", example = "公開招標")private String tenderMethod;@Schema(description = "招標金額(萬元)", example = "500.80")private BigDecimal tenderAmount;@Schema(description = "發布時間")private LocalDateTime publishTime;@Schema(description = "截止時間")private LocalDateTime deadline;@Schema(description = "項目狀態", example = "招標中")private String projectStatus;
}

2. 參數類(Param)配置

import io.swagger.v3.oas.annotations.media.Schema;
import lombok.Data;@Data
@Schema(description = "招標數據明細查詢參數")
public class TenderDetailParam {@Schema(description = "招標編號", example = "ZB2023001")private String tenderNo;@Schema(description = "項目名稱", example = "城市道路改造工程")private String projectName;@Schema(description = "招標單位", example = "市政建設有限公司")private String tenderUnit;@Schema(description = "頁碼", example = "1", required = true)private Integer pageNum;@Schema(description = "每頁條數", example = "10", required = true)private Integer pageSize;
}

3. 分頁響應類配置

import io.swagger.v3.oas.annotations.media.Schema;
import lombok.Data;import java.util.List;@Data
@Schema(description = "分頁查詢響應對象")
public class PageResultVO<T> {@Schema(description = "總記錄數", example = "100")private long total;@Schema(description = "總頁數", example = "10")private int pages;@Schema(description = "當前頁碼", example = "1")private int pageNum;@Schema(description = "每頁條數", example = "10")private int pageSize;@Schema(description = "數據列表")private List<T> list;
}

4. 接口方法配置

import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.Parameter;
import io.swagger.v3.oas.annotations.media.Content;
import io.swagger.v3.oas.annotations.media.Schema;
import io.swagger.v3.oas.annotations.responses.ApiResponse;
import io.swagger.v3.oas.annotations.tags.Tag;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;@RestController
@RequestMapping("/tender")
@Tag(name = "招標數據管理", description = "招標數據相關接口")
public class TenderController {private final TenderService tenderService;// 構造函數注入服務public TenderController(TenderService tenderService) {this.tenderService = tenderService;}@Operation(summary = "查詢寬表：獲取招標數據明細",description = "根據條件查詢招標數據明細，支持分頁",responses = {@ApiResponse(responseCode = "200", description = "查詢成功",content = @Content(schema = @Schema(implementation = PageResultVO.class))),@ApiResponse(responseCode = "400", description = "請求參數錯誤"),@ApiResponse(responseCode = "500", description = "服務器內部錯誤")})@PostMapping("/detail")public PageResultVO<TenderDetailVO> getTenderDetail(@Parameter(description = "查詢參數", required = true)@RequestBody TenderDetailParam param) {// 調用服務層方法獲取數據return tenderService.queryTenderDetail(param);}
}

關鍵配置說明：

1. 核心注解變化：

   • 用@Schema替代了swagger2的@ApiModelProperty
   • 用@Tag替代了@Api
   • 用@Operation替代了@ApiOperation
   • 用@Parameter替代了@ApiParam
   • 用@ApiResponse和@Content組合替代了@ApiResponses

2. VO配置要點：

   • 使用@Schema注解描述類和字段信息
   • 通過example屬性設置示例值
   • required屬性標識是否為必填字段

3. 接口方法配置：

   • @Operation中可以直接定義響應信息
   • 通過@Content和@Schema指定響應數據類型
   • @Parameter用于描述請求參數

4. 分頁處理：

   • 保持分頁響應對象的通用性
   • 在@ApiResponse中通過implementation指定具體的泛型實現

配置完成后，訪問springdoc的默認地址http://localhost:8080/swagger-ui.html即可查看生成的API文檔。這種配置方式更符合OpenAPI 3.0規范，并且能更好地與spring生態集成。

3. 請求對象配置

請求對象通常是用于接收客戶端請求的對象。在上面的示例中，Item 類就是請求對象。您可以使用 @RequestBody 注解將請求體映射到該對象。

訪問 API 文檔

在啟動應用程序后，您可以通過訪問 http://localhost:8080/swagger-ui.html 來查看生成的 Swagger UI，您將看到所有配置的 API 及其文檔。