<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 及其文档。