好家伙,今天終于開始用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;}
}
一款免費的在線文檔格式轉換工具在線文檔轉換
