SpringBoot整合knife4j（快速入门超详细版）
😊 @ 作者： Eric
💖 @ 主页： https://blog.csdn.net/weixin_47316183?type=blog
🎉 @ 主题：SpringBoot整合knife4j（快速入门超详细版）
⏱️ @ 创作时间： 2023年08月01日
1、什么是Knife4j
在日常开发中，写接口文档是我们必不可少的，而Knife4j就是一个接口文档工具，可以看作是Swagger的升级版，但是界面比Swagger更好看，功能更丰富
早期，swagger-boostrap-ui是1.x版本，如今swagger-bootsrap-ui到2.x，同时也更改名字Knife4j，适用于单体和微服务项目。
Knife4j官方网站：https://doc.xiaominfo.com/
2、SpringBoor整合Knife4j
2.1、Knife4j配置
1、创建一个SpringBoot项目
2、引入Knife4j相关依赖（这里顺带引入了Lombok依赖）
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>knife4j-spring-boot-starter</artifactId>
<version>2.0.8</version>
</dependency>
<dependency>
<groupId>org.projectlombok</groupId>
<artifactId>lombok</artifactId>
</dependency>
3、创建Knife4J配置类
package com.eric.springbootknife4j.config;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.ParameterBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.schema.ModelRef;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.service.Parameter;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2WebMvc;
import java.util.ArrayList;
import java.util.List;
/**
* Swagger2配置信息
* 这里分了两组显示
* 第一组是api，当作用户端接口
* 第二组是admin，当作后台管理接口
* 也可以根据实际情况来减少或者增加组
*
* @author Eric
* @date 2023-07-30 22:17
*/
@Configuration
@EnableSwagger2WebMvc
public class Swagger2Config {
private ApiInfo adminApiInfo() {
return new ApiInfoBuilder()
.title("Eric-SpringBoot整合Knife4j-API文档")
.description("本文档描述了SpringBoot如何整合Knife4j")
.version("1.0")
.contact(new Contact("Eric", "https://blog.csdn.net/weixin_47316183?type=blog", "ericsyn@foxmail.com"))
.build();
}
private ApiInfo webApiInfo() {
return new ApiInfoBuilder()
.title("Eric-SpringBoot整合Knife4j-API文档")
.description("本文档描述了SpringBoot如何整合Knife4j")
.version("1.0")
.contact(new Contact("Eric", "https://blog.csdn.net/weixin_47316183?type=blog", "ericsyn@foxmail.com"))
.build();
}
/**
* 第一组：api
* @return
*/
@Bean
public Docket webApiConfig() {
List<Parameter> pars = new ArrayList<>();
ParameterBuilder tokenPar = new ParameterBuilder();
tokenPar.name("userId")
.description("用户token")
//.defaultValue(JwtHelper.createToken(1L, "admin"))
.defaultValue("1")
.modelRef(new ModelRef("string"))
.parameterType("header")
.required(false)
.build();
pars.add(tokenPar.build());
Docket webApi = new Docket(DocumentationType.SWAGGER_2)
.groupName("用户端接口")
.apiInfo(webApiInfo())
.select()
//只显示api路径下的页面
.apis(RequestHandlerSelectors.basePackage("com.eric.springbootknife4j"))
.paths(PathSelectors.regex("/api/.*"))
.build()
.globalOperationParameters(pars);
return webApi;
}
/**
* 第二组：admin
* @return
*/
@Bean
public Docket adminApiConfig() {
List<Parameter> pars = new ArrayList<>();
ParameterBuilder tokenPar = new ParameterBuilder();
tokenPar.name("adminId")
.description("用户token")
.defaultValue("1")
.modelRef(new ModelRef("string"))
.parameterType("header")
.required(false)
.build();
pars.add(tokenPar.build());
Docket adminApi = new Docket(DocumentationType.SWAGGER_2)
.groupName("后台接口")
.apiInfo(adminApiInfo())
.select()
//只显示admin路径下的页面
.apis(RequestHandlerSelectors.basePackage("com.eric.springbootknife4j"))
.paths(PathSelectors.regex("/admin/.*"))
.build()
.globalOperationParameters(pars);
return adminApi;
}
}
2.2、使用Knife4j
1、创建一个实体类
package com.eric.springbootknife4j.entity;
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.Builder;
import lombok.Data;
/**
* @author Eric
* @date 2023-07-31 9:55
*/
@ApiModel("用户实体类")
@Data
@Builder
public class SwaggerUser {
@ApiModelProperty("用户Id")
private Long id;
@ApiModelProperty("用户名称")
private String name;
}
2、对应接口，这里我为了大家看的方便，也是分了两个控制器，也是根据api和admin来分的
admin
package com.eric.springbootknife4j.admin;
import com.eric.springbootknife4j.entity.SwaggerUser;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;
import java.util.ArrayList;
import java.util.List;
/**
* @author Eric
* @date 2023-07-31 9:50
*/
@Api(tags = "用户端控制器")
@RestController
@RequestMapping("/admin")
public class AdminController {
@ApiOperation(value = "获取数据")
@GetMapping("/test")
public List<SwaggerUser> test(@ApiParam(name = "id",value = "用户Id") Long id,
@ApiParam(name = "name",value = "用户名称") String name){
List<SwaggerUser> list = new ArrayList<>();
list.add(SwaggerUser.builder().id(id).name(name).build());
return list;
}
}
api
package com.eric.springbootknife4j.api;
import com.eric.springbootknife4j.entity.SwaggerUser;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;
import java.util.ArrayList;
import java.util.List;
/**
* @author Eric
* @date 2023-07-31 9:50
*/
@Api(tags = "用户端控制器")
@RestController
@RequestMapping("/api")
public class ApiController {
@ApiOperation(value = "获取数据")
@GetMapping("/test")
public List<SwaggerUser> test(@ApiParam(name = "id",value = "用户Id") Long id,
@ApiParam(name = "name",value = "用户名称") String name){
List<SwaggerUser> list = new ArrayList<>();
list.add(SwaggerUser.builder().id(id).name(name).build());
return list;
}
}
2.3、效果
此时运行项目，访问 IP+端口/doc.html
例如：http://127.0.0.1:8080/doc.html
这就是首页
包括也是按照我们的配置文件来分组显示了，这里可根据自己项目的实际情况，按照微服务来分、按照功能目录来分都是可以的
如下就是我们的实体类，发现我们写的注释也都自动生成了
下面就是我们的接口调试界面了
自带路径、接口说明、参数说明，只要我们写了解释，这里都会显示
此时我们也可以点击调试，然后点击发送，就能看到我们的返回信息了，并且如果我们的返回实体类上有注解注释的，这里也是会显示的
总结
怎么样，是不是特别的方便和简单~