Spring-boot3.4最新版整合swagger和Mybatis-plus

好家伙,今天终于开始用spring-boot3开始写项目了，以后要彻底告别1.x和2.x了，同样的jdk也来到了最低17的要求了,废话不多说直接开始

这是官方文档的要求jdk最低是17 maven最低是3.6

一. 构建工程,这一步就不需要给大家解释了吧

二. 整合Knife4j

1.大于 spring-boot 2.6.x 小于 spring-boot3.x的版本

<swagger.version>3.0.0</swagger.version> <knife4j.version>3.0.3</knife4j.version> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-boot-starter</artifactId> <version>${swagger.version}</version> </dependency> <dependency> <groupId>com.github.xiaoymin</groupId> <artifactId>knife4j-spring-boot-starter</artifactId> <version>${knife4j.version}</version> </dependency>

2. 然后配置接口文档

@Configuration @EnableOpenApi public class Knife4jConfig { @Bean public Docket createResetApi(){ return new Docket(DocumentationType.OAS_30) .apiInfo(apiInfo()) .select() .apis(RequestHandlerSelectors.withClassAnnotation(RestController.class)) .paths(PathSelectors.any()) .build(); } @Bean public Docket adminApi(){ return new Docket(DocumentationType.OAS_30) .apiInfo(apiInfo()) .groupName("后台管理") .select() .apis(RequestHandlerSelectors.basePackage("com.demo.admin.controller")) .paths(PathSelectors.any()) .build(); } @Bean public Docket webApi(){ return new Docket(DocumentationType.OAS_30) .apiInfo(apiInfo()) .groupName("web端") .select() .apis(RequestHandlerSelectors.basePackage("com.demo.web.controller")) .paths(PathSelectors.any()) .build(); } private ApiInfo apiInfo() { return new ApiInfoBuilder() .title("接口文档标题") .description("描述") .contact(new Contact("你是哪一个", "127.0.0.1:8080", "email")) .license("The Apache License") .termsOfServiceUrl("http://127.0.0.1:8080/api") .version("1.0") .build(); }

3. 在代码中使用

@Api(tags = "首页模块") @RestController public class IndexController { @ApiImplicitParam(name = "name",value = "姓名",required = true) @ApiOperation(value = "向客人问好") @GetMapping("/sayHi") public ResponseEntity<String> sayHi(@RequestParam(value = "name")String name){ return ResponseEntity.ok("Hi:"+name); } } @Data @ApiModel public class BaseQuery implements Serializable { private static final long serialVersionUID = 1L; @ApiModelProperty(value = "当前页码") Integer pageNum = PagesConstant.DEFAULT_PAGE; @Range(min = 1, max = 200, message = "每页条数，取值范围 1-200") @ApiModelProperty(value = "每页条数 默认200") Integer pageSize = PagesConstant.DEFAULT_PAGE_SIZE; @ApiModelProperty(value = "排序字段") String order; @ApiModelProperty(value = "是否升序") boolean asc; }

下面是新版的使用方式

1.添加最新的依赖

<dependency> <groupId>com.github.xiaoymin</groupId> <artifactId>knife4j-openapi3-jakarta-spring-boot-starter</artifactId> <version>${knife4j.version}</version> </dependency>

2.编写配置文件,没有了2中的Docket,groupName,select，apis 等等…总的来说新版的变得更为简单了

@Configuration public class OpenApiConfig { /** * 默认 API 分组，包含前端和后端接口 */ @Bean public GroupedOpenApi defaultApi() { return GroupedOpenApi.builder() .group("default") // 分组名称 .packagesToScan("com.demo") // 匹配路径，可以根据实际情况调整 .build(); } /** * 前端 API 分组，只包含前端接口 */ @Bean public GroupedOpenApi webApi() { return GroupedOpenApi.builder() .group("前端接口") // 分组名称 .pathsToMatch("/api/web/**") // 前端接口路径 .build(); } /** * 后端 API 分组，只包含后端接口 */ @Bean public GroupedOpenApi adminApi() { return GroupedOpenApi.builder() .group("后端接口") // 分组名称 .pathsToMatch("/api/admin/**") // 后端接口路径 .build(); } /** * 定制全局信息 */ @Bean public OpenApiCustomizer customOpenApiCustomizer() { return openApi -> openApi.info( new Info() .title("API 文档") .description("API 文档描述") .version("1.0.0") .contact(new Contact().name("API Team").email("api-team@example.com")) ); }

3.其中最重要的就是packagesToScan和pathsToMatch了，具体是什么意思我们可以查看源代码给大家解释一下

// 分组名称，用于标识 OpenAPI 配置的组。 private final String group; // 要匹配的路径列表，定义哪些路径会生成 OpenAPI 文档。 private final List<String> pathsToMatch; // 要扫描的包名列表，用于发现生成 OpenAPI 文档的类。 private final List<String> packagesToScan; // 要排除的包名列表，这些包中的内容不会生成 OpenAPI 文档。 private final List<String> packagesToExclude; // 要排除的路径列表，这些路径不会生成 OpenAPI 文档。 private final List<String> pathsToExclude; // 要匹配的响应类型列表，例如 "application/json"。 private final List<String> producesToMatch; // 要匹配的 HTTP 头部列表，用于限定生成文档的请求。 private final List<String> headersToMatch; // 要匹配的请求体类型列表，例如 "application/json"。 private final List<String> consumesToMatch; // 显示名称，用于描述 OpenAPI 配置的组。 private final String displayName; // 自定义 OpenAPI 文档的定制器列表。 private List<OpenApiCustomizer> openApiCustomizers; // 自定义 OpenAPI 操作（API 方法）文档的定制器列表。 private List<OperationCustomizer> operationCustomizers; // 自定义路由操作的文档定制器列表。 private List<RouterOperationCustomizer> routerOperationCustomizers; // 用于过滤哪些方法应该包含在 OpenAPI 文档中的过滤器列表。 private List<OpenApiMethodFilter> openApiMethodFilters;

4.在使用的时候也有一些变化,我们分了三个组 对应了3个模块

@Tag(name = "/公共接口") @RestController @RequestMapping("/test") public class AccountController { @Operation(summary = "获取所有接口 default") @GetMapping("/index") public String index(){ return "Hello World"; } } @Tag(name = "后端接口") @RestController @RequestMapping(value = "/api/admin") public class AdminController { @Operation(summary = "获取admin接口") @GetMapping(value = "/index") public String index(){ return "Hello Admin"; } } @Tag(name = "前端接口") @RestController @RequestMapping(value = "/api/web") public class WebController { @Operation(summary = "获取前端接口") @GetMapping(value = "/index") public String index(){ return "Hello Web"; } }

5.这样就配置好分组信息以及接口信息了,访问localhost:8080/doc.html 就会出现如下图这样

1. default默认分组
   

2. web 分组
   

3. admin 分组
   

6.这样接口文档和接口分组就配置好了 在配置文件中(我一般用yml)也可以配置

三.整合mybatis-plus,说实话新版的没太大的变化

1.mybatis-plus 3.5.9 起，分页插件已分离出来。如需使用，则需单独引入依赖

2.也就是说在使用这个版本的时候要多加一个依赖了

<dependency> <groupId>com.baomidou</groupId> <artifactId>mybatis-plus-spring-boot3-starter</artifactId> <version>${mybatis.plus.version}</version> </dependency> <dependency> <groupId>com.baomidou</groupId> <artifactId>mybatis-plus-jsqlparser</artifactId> <version>${mybatis.plus.version}</version> </dependency>

3.然后在配置文件中在进行配置就可以和以前一样了

@Configuration @MapperScan("scan.your.mapper.package") public class MybatisPlusConfig { /** * 添加分页插件 */ @Bean public MybatisPlusInterceptor mybatisPlusInterceptor() { MybatisPlusInterceptor interceptor = new MybatisPlusInterceptor(); interceptor.addInnerInterceptor(new PaginationInnerInterceptor(DbType.MYSQL)); // 如果配置多个插件, 切记分页最后添加 // 如果有多数据源可以不配具体类型, 否则都建议配上具体的 DbType return interceptor; } }

一款免费的在线文档格式转换工具在线文档转换