在现代 Web 应用开发中，API 文档的重要性不言而喻。清晰、准确、易用的 API 文档不仅可以方便开发者理解和使用 API，还能提高团队协作效率。Knife4j 是一个基于 Swagger 的增强型 API 文档工具，它可以为 Spring Boot 项目生成美观、易于交互的 API 文档，本文将介绍如何在 Spring Boot 项目中整合 Knife4j，并提供详细的代码示例和最佳实践。
一、为什么选择 Knife4j？
Knife4j 是一个基于 Swagger 的增强型 API 文档框架，相比于 Swagger UI，Knife4j 提供了更强大的功能和更好的用户体验：
- 界面美观： Knife4j 提供了更加美观和现代的界面，使得 API 文档更具吸引力。
- 功能强大： Knife4j支持在线调试、参数示例、离线文档导出等多种实用功能。
- 易于集成： Knife4j 可以轻松地与 Spring Boot 集成。
- 支持多种主题： Knife4j 提供了多种主题，可以自定义 API 文档的风格。
- 更好的可读性： Knife4j 在 API文档的呈现上做了优化，使其更易于阅读和理解。
二、Spring Boot 整合 Knife4j实践
2.1 添加 Knife4j 依赖
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>knife4j-spring-boot-starter</artifactId>
<version>3.0.3</version>
</dependency>
<dependency>
<artifactId>guava</artifactId>
<groupId>com.google.guava</groupId>
<version>29.0-jre</version>
</dependency>
注意： 请使用合适的版本号，确保你的 Spring Boot 版本与 Knife4j 和 Swagger 兼容。
2.2 创建 Swagger 配置类
import com.github.xiaoymin.knife4j.spring.annotations.EnableKnife4j;
import com.google.common.base.Function;
import com.google.common.base.Optional;
import com.google.common.base.Predicate;
import org.springframework.boot.autoconfigure.condition.ConditionalOnWebApplication;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;
import springfox.documentation.RequestHandler;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
@Configuration
@EnableSwagger2
@EnableKnife4j
@ConditionalOnWebApplication
public class SwaggerConfig implements WebMvcConfigurer {
/**
* 定义分隔符
*/
private static final String SPLITOR = ";";
@Bean(value = "systemApi")
public Docket createSystemRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.groupName("1.系统管理模块")
.select()
.apis(basePackage("com.extend.chk.system.controller"))
.paths(PathSelectors.any())
.build();
}
@Bean(value = "reportApi")
public Docket createReportRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.groupName("2.数据可视化模块")
.select()
.apis(basePackage("com.extend.chk.report.controller"))
.paths(PathSelectors.any())
.build();
}
@Bean(value = "warnApi")
public Docket createWarnRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.groupName("3.预警模块")
.select()
.apis(basePackage(("com.extend.chk.warn.controller")))
.paths(PathSelectors.any())
.build();
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.description("学习管理平台接口文档")
.version("v1.0.0")
.title("学习管理平台接口文档")
.build();
}
/**
* 重写basePackage方法，使能够实现多包访问
* @param basePackage
* @return
*/
public static Predicate<RequestHandler> basePackage(final String basePackage) {
return input -> declaringClass(input).transform(handlerPackage(basePackage)).or(true);
}
private static Function<Class<?>, Boolean> handlerPackage(final String basePackage) {
return input -> {
// 循环判断匹配
for (String strPackage : basePackage.split(SPLITOR)) {
boolean isMatch = input.getPackage().getName().startsWith(strPackage);
if (isMatch) {
return true;
}
}
return false;
};
}
private static Optional<? extends Class<?>> declaringClass(RequestHandler input) {
return Optional.fromNullable(input.declaringClass());
}
/**
* 配置静态资源
* @param registry
*/
@Override
public void addResourceHandlers(ResourceHandlerRegistry registry) {
registry.addResourceHandler("/static/**").addResourceLocations("classpath:/static/");
}
}
@Configuration: 标识这是一个配置类，用来定义 Bean 或其他配置信息。@EnableSwagger2: 启用 Swagger 2 来生成和管理 RESTful API 的文档。@EnableKnife4j：增强 Swagger UI 的展示效果，提供更美观、功能更丰富的 API 文档界面。@ConditionalOnWebApplication：确保上述配置仅在应用程序为 Web 应用时才生效。@Bean: 创建 Docket Bean，用于配置 Swagger 文档信息。apiInfo(): 配置 API的基本信息，例如标题、描述、版本号等。apis(basePackage(("com.extend.chk.warn.controller"))): 指定生成API 文档的 Controller 所在的包。paths(PathSelectors.any()): 定义路径过滤规则，决定哪些 URL 路径应被包含在文档中，这里设置为所有路径。groupName("1.系统管理模块")：为生成的 API 分组指定名称。这可以将不同的 API 接口按功能或模块进行分类展示。
2.3 在类上使用 Swagger 注解
2.3.1 在controller里面使用Swagger 注解
@Api(tags = "项目管理")
@RestController
@RequestMapping("/project/manage")
public class ProjectManageController extends BaseController {
@Autowired
private ProjectManageService ProjectManageService;
@ApiOperation(value = "查询项目列表")
@GetMapping("/list")
public Result<PageDataInfo<ProjectManage>> queryProjectManageList(ProjectManageReq req) {
return success(buildPageDataInfo(ProjectManageService.queryProjectManageList(req)));
}
@ApiOperation(value = "查询项目详情")
@GetMapping("/query")
public Result<ProjectManage> queryProjectManageById(Integer workspaceId, Integer projectId) {
return success(ProjectManageService.queryProjectManageById(workspaceId, projectId));
}
@ApiOperation(value = "项目新增")
@PostMapping(value = "/add")
@Log(title = "项目新增", businessType = BusinessType.INSERT)
public Result addProjectManage(@Validated @RequestBody ProjectManage ProjectManage) {
ProjectManageService.addProjectManage(ProjectManage);
return success();
}
@ApiOperation(value = "项目修改")
@PostMapping(value = "/update")
@Log(title = "项目修改", businessType = BusinessType.UPDATE)
public Result updateProjectManage(@Validated @RequestBody ProjectManage ProjectManage) {
ProjectManageService.updateProjectManage(ProjectManage);
return success();
}
@ApiOperation(value = "项目删除")
@ApiImplicitParams({
@ApiImplicitParam(name = "workspaceId", value = "空间id", required = true),
@ApiImplicitParam(name = "projectId", value = "项目id", required = true)
})
@PutMapping(value = "/delete")
@Log(title = "项目删除", businessType = BusinessType.DELETE)
public Result operateProjectManage(Integer workspaceId, Integer projectId) {
ProjectManageService.operateProjectManage(workspaceId, projectId);
return success();
}
}
@Api: 用于描述 Controller 的基本信息，例如分类标签。@ApiOperation: 用于描述 API的基本信息，例如接口名称、描述等。@ApiImplicitParam: 用于描述 API的参数信息，例如参数名称、类型、是否必填等。
2.3.2 在请求类和返回类里面使用Swagger 注解
@ApiModel(value = "ProjectManage对象", description = "项目管理表")
public class ProjectManage extends BaseEntity<ProjectManage> {
private static final long serialVersionUID = 1L;
@ApiModelProperty("主键id")
private Integer id;
@ApiModelProperty("项目名称")
private String name;
@ApiModelProperty("项目负责人id")
private String ownerId;
@ApiModelProperty("项目成员id")
private String memberId;
@ApiModelProperty("工作空间id")
private Integer workspaceId;
@ApiModelProperty("项目状态(1-有效 2-失效)")
private String status;
@Override
public Serializable pkVal() {
return this.id;
}
}
@ApiModel：用于描述一个模型类（通常是一个 DTO 或实体类），提供该模型的详细信息，如名称、描述等。它使得生成的 API文档能够清晰地展示数据模型的用途和结构。@ApiModelProperty：用于描述模型类中的具体字段，指定字段的名称、类型、是否必填、默认值、备注等信息。这有助于开发者更好地理解每个字段的意义和用法。
2.4 访问 Knife4j 文档
启动 Spring Boot 应用，并在浏览器中访问以下地址，即可查看 Knife4j 生成的 API 文档：
http://localhost:8080/extend/doc.html#/home
三、最佳实践
- 使用 Swagger 注解描述 API： 使用 Swagger 注解详细描述 API 的参数、响应、错误码等，提高文档的可读性。
- 根据API 分组： 使用 Swagger 的分组功能，将 API 分类展示，方便用户查找。
- 添加 API 示例： 在 Swagger注解中添加 API 示例，帮助用户快速了解 API 的使用方法。
- 保持 API 文档与代码同步： 确保 API文档和代码同步更新，避免出现文档与代码不一致的问题。
- 使用清晰的 API 命名： 使用清晰的 API 命名和参数命名，提高 API的可读性。
