springdoc-openapi-ui的使用教程

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