当前位置：首页 > news >正文

springdoc-openapi-ui的使用教程

news 2025/7/22 10:25:15

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

springdoc-openapi-ui 是一个用于生成 OpenAPI 文档的库，它与 Swagger 的关系如下：

区别

OpenAPI 规范：
- springdoc-openapi 是基于 OpenAPI 3.0 规范的实现，而 Swagger 2.0 是较早的版本。OpenAPI 3.0 提供了更丰富的功能和更好的支持。
集成方式：
- springdoc-openapi 提供了更简单的集成方式，特别是在 Spring Boot 应用中。它可以自动扫描控制器和模型，并生成相应的 API 文档。
功能：
- 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);}
}

关键配置说明：

核心注解变化：
- 用@Schema替代了swagger2的@ApiModelProperty
- 用@Tag替代了@Api
- 用@Operation替代了@ApiOperation
- 用@Parameter替代了@ApiParam
- 用@ApiResponse和@Content组合替代了@ApiResponses
VO配置要点：
- 使用@Schema注解描述类和字段信息
- 通过example属性设置示例值
- required属性标识是否为必填字段
接口方法配置：
- @Operation中可以直接定义响应信息
- 通过@Content和@Schema指定响应数据类型
- @Parameter用于描述请求参数
分页处理：
- 保持分页响应对象的通用性
- 在@ApiResponse中通过implementation指定具体的泛型实现