好家伙,今天终于开始用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 {@Beanpublic Docket createResetApi(){return new Docket(DocumentationType.OAS_30).apiInfo(apiInfo()).select().apis(RequestHandlerSelectors.withClassAnnotation(RestController.class)).paths(PathSelectors.any()).build();}@Beanpublic Docket adminApi(){return new Docket(DocumentationType.OAS_30).apiInfo(apiInfo()).groupName("后台管理").select().apis(RequestHandlerSelectors.basePackage("com.demo.admin.controller")).paths(PathSelectors.any()).build();}@Beanpublic 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 分组，包含前端和后端接口*/@Beanpublic GroupedOpenApi defaultApi() {return GroupedOpenApi.builder().group("default") // 分组名称.packagesToScan("com.demo") // 匹配路径，可以根据实际情况调整.build();}/*** 前端 API 分组，只包含前端接口*/@Beanpublic GroupedOpenApi webApi() {return GroupedOpenApi.builder().group("前端接口") // 分组名称.pathsToMatch("/api/web/**") // 前端接口路径.build();}/*** 后端 API 分组，只包含后端接口*/@Beanpublic GroupedOpenApi adminApi() {return GroupedOpenApi.builder().group("后端接口") // 分组名称.pathsToMatch("/api/admin/**") // 后端接口路径.build();}/*** 定制全局信息*/@Beanpublic 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 就会出现如下图这样
-
default默认分组
-
web 分组
-
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 {/*** 添加分页插件*/@Beanpublic MybatisPlusInterceptor mybatisPlusInterceptor() {MybatisPlusInterceptor interceptor = new MybatisPlusInterceptor();interceptor.addInnerInterceptor(new PaginationInnerInterceptor(DbType.MYSQL)); // 如果配置多个插件, 切记分页最后添加// 如果有多数据源可以不配具体类型, 否则都建议配上具体的 DbTypereturn interceptor;}
}
一款免费的在线文档格式转换工具在线文档转换
