效率工具

• 推荐一个程序员常用的工具网站：程序员常用工具（http://tools.cxyroad.com），有时间戳、JSON格式化、文本对比、HASH生成、UUID生成等常用工具，效率加倍嘎嘎好用。

云服务器

• 云服务器限时免费领：轻量服务器2核4G
• 腾讯云：2核2G4M云服务器新老同享99元/年，续费同价
• 阿里云：2核2G3M的ECS服务器只需99元/年，续费同价

整合Spring Boot框架集成Knife4j

在现代Web开发中，API文档对于开发者来说至关重要。它不仅能帮助前后端开发者明确接口的使用方式，还能提供接口调试和验证功能。在Spring Boot项目中，集成Swagger是一个常见的选择。而Knife4j（前身是Swagger Bootstrap UI）在Swagger的基础上，提供了更丰富的功能和更友好的界面。本篇文章将详细介绍如何在Spring Boot项目中集成Knife4j，实现API文档的自动生成和管理。

一、什么是Knife4j

Knife4j是对Swagger的增强，提供了更丰富的功能和更友好的UI。它能够生成更加直观和美观的API文档，并且支持接口调试、接口分组、Markdown文档等功能，极大地方便了开发和测试。

1.1 Knife4j的主要功能

• 美观的UI：提供了比Swagger UI更加美观的界面。
• 接口调试：可以直接在页面上调试接口，查看返回结果。
• 接口分组：支持对API进行分组管理，方便查找和管理。
• Markdown支持：可以在文档中嵌入Markdown格式的说明，提升文档的可读性。

二、环境准备

在开始之前，确保你的开发环境中已经安装了以下工具：

• JDK 1.8或更高版本
• Maven或Gradle
• IDE（IntelliJ IDEA或Eclipse等）

三、Spring Boot项目中集成Knife4j

3.1 创建Spring Boot项目

首先，创建一个新的Spring Boot项目。如果你已经有了一个现成的Spring Boot项目，可以跳过此步骤。

3.2 添加依赖

在Spring Boot项目中添加Knife4j的依赖。以Maven为例，在pom.xml文件中添加以下依赖：

<dependencies><!-- Spring Boot 依赖 --><dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-web</artifactId></dependency><!-- Knife4j 依赖 --><dependency><groupId>com.github.xiaoymin</groupId><artifactId>knife4j-spring-boot-starter</artifactId><version>4.0.0</version></dependency><!-- Swagger 依赖 --><dependency><groupId>io.springfox</groupId><artifactId>springfox-boot-starter</artifactId><version>3.0.0</version></dependency>
</dependencies>

如果你使用Gradle，则在build.gradle文件中添加以下依赖：

dependencies {implementation 'org.springframework.boot:spring-boot-starter-web'implementation 'com.github.xiaoymin:knife4j-spring-boot-starter:4.0.0'implementation 'io.springfox:springfox-boot-starter:3.0.0'
}

3.3 配置Swagger和Knife4j

在Spring Boot项目的配置文件中进行Swagger和Knife4j的基本配置。通常在src/main/resources目录下创建或修改application.yml或application.properties文件。

使用application.yml进行配置：

spring:application:name: demo-applicationknife4j:enable: truetitle: API文档description: API接口文档version: 1.0.0contact:name: 开发者url: http://example.comemail: developer@example.comswagger:api-docs:path: /v3/api-docsenabled: truedocket:default:group-name: defaultpaths-to-match: /**api-info:title: API文档version: 1.0.0description: API接口文档contact:name: 开发者url: http://example.comemail: developer@example.com

使用application.properties进行配置：

spring.application.name=demo-applicationknife4j.enable=true
knife4j.title=API文档
knife4j.description=API接口文档
knife4j.version=1.0.0
knife4j.contact.name=开发者
knife4j.contact.url=http://example.com
knife4j.contact.email=developer@example.comswagger.api-docs.path=/v3/api-docs
swagger.enabled=true
swagger.docket.default.group-name=default
swagger.docket.default.paths-to-match=/**
swagger.docket.default.api-info.title=API文档
swagger.docket.default.api-info.version=1.0.0
swagger.docket.default.api-info.description=API接口文档
swagger.docket.default.api-info.contact.name=开发者
swagger.docket.default.api-info.contact.url=http://example.com
swagger.docket.default.api-info.contact.email=developer@example.com

3.4 创建Swagger配置类

在项目中创建一个Swagger配置类，启用Swagger和Knife4j。

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;@Configuration
@EnableSwagger2
public class SwaggerConfig {@Beanpublic Docket api() {return new Docket(DocumentationType.OAS_30).select().apis(RequestHandlerSelectors.basePackage("com.example.demo")).paths(PathSelectors.any()).build();}
}

在这里，我们创建了一个Swagger配置类SwaggerConfig，并在其中定义了一个Docket bean，用于扫描指定包中的API接口。

3.5 创建示例Controller

为了验证Swagger和Knife4j的集成效果，我们创建一个简单的Controller：

import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;@RestController
@RequestMapping("/api")
@Api(tags = "示例接口")
public class DemoController {@GetMapping("/hello")@ApiOperation("问候接口")public String hello() {return "Hello, Knife4j!";}
}

3.6 运行项目并访问Knife4j界面

启动Spring Boot项目，打开浏览器并访问http://localhost:8080/doc.html，即可看到Knife4j生成的API文档界面。

四、高级配置和优化

4.1 接口分组

在实际项目中，API接口可能会很多，可以使用分组功能来管理不同模块的接口。在SwaggerConfig中配置多个Docket bean来实现分组：

@Configuration
@EnableSwagger2
public class SwaggerConfig {@Beanpublic Docket groupOne() {return new Docket(DocumentationType.OAS_30).groupName("组一").select().apis(RequestHandlerSelectors.basePackage("com.example.demo.group1")).paths(PathSelectors.any()).build();}@Beanpublic Docket groupTwo() {return new Docket(DocumentationType.OAS_30).groupName("组二").select().apis(RequestHandlerSelectors.basePackage("com.example.demo.group2")).paths(PathSelectors.any()).build();}
}

4.2 使用注解增强文档

可以通过Swagger的注解来增强API文档的可读性和信息量，如@ApiOperation、@ApiParam、@ApiModel等。

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;@ApiModel(description = "用户实体")
public class User {@ApiModelProperty(value = "用户ID", example = "1")private Long id;@ApiModelProperty(value = "用户名", example = "JohnDoe")private String username;// getters and setters
}

4.3 配置安全认证

如果API需要认证授权，可以在Swagger配置中添加安全配置：

import springfox.documentation.service.ApiKey;
import springfox.documentation.service.SecurityReference;
import springfox.documentation.spi.service.contexts.SecurityContext;@Configuration
@EnableSwagger2
public class SwaggerConfig {@Beanpublic Docket api() {return new Docket(DocumentationType.OAS_30).select().apis(RequestHandlerSelectors.any()).paths(PathSelectors.any()).build().securitySchemes(Arrays.asList(apiKey())).securityContexts(Arrays.asList(securityContext()));}private ApiKey apiKey() {return new ApiKey("JWT", "Authorization", "header");}private SecurityContext securityContext() {return SecurityContext.builder().securityReferences(defaultAuth()).build();}private List<SecurityReference> defaultAuth() {AuthorizationScope authorizationScope = new AuthorizationScope("global", "accessEverything");AuthorizationScope[] authorizationScopes = new AuthorizationScope[1];authorizationScopes[0] = authorizationScope;return Arrays.asList(new SecurityReference("JWT", authorizationScopes));}
}

五、总结

通过本文的介绍，我们了解了如何在Spring Boot项目中集成Knife4j，提升API文档的美观性和可用性。Knife4j不仅提供了友好的界面，还支持丰富的功能，如接口调试、接口分组和Markdown文档等。

在实际项目中，合理配置和使用Knife4j，不仅能提升开发效率，还能为前后端联调和测试提供极大的便利。如果你还没有在项目中使用Knife4j，不妨尝试一下，相信你会喜欢上这个强大的工具。