在Spring中使用Knife4j进行API文档生成与管理的操作方法

什么是 Knife4j

Knife4j 是为Java MVC 框架（如Spring Boot、Spring MVC等）集成 Swagger 生成 API 文档的增强解决方案，它基于 Swagger 的核心功能，通过定制化的前端界面和一些额外的特性，拥有比原生 Swagger UI 更美观、直观的操作界面。

Knife4j支持离线文档下载，方便在没有网络连接的情况下查阅 API 文档，拥有接口排序功能，使得 API 文档的结构更加清晰有序，也具备动态参数调试能力，能够实时修改请求参数并查看响应结果，方便开发过程中的接口测试。

在Spring中集成 Knife4j 的准备工作

搭建好一个基于Spring的项目环境，可以是 Spring Boot 项目或者传统的 Spring MVC 项目，以 Spring Boot 项目为例，首先需要在 pom.xml 文件中引入必要的 Spring Web 相关依赖：

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
</dependency>

在 Maven 项目中，添加 Knife4j 的核心依赖：

<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-spring-boot-starter</artifactId>
    <version>3.0.2</version>
</dependency>

在config层中创建一个配置类来配置 Knife4j：

@Configuration
@EnableKnife4j
public class Knife4jConfig {
 
    @Bean
    public Docket docket() {
        return new Docket(DocumentationPlugin.DEFAULT_GROUP_NAME)
              .apiInfo(apiInfo())
              .select()
              .apis(RequestHandlerSelectors.basePackage("//Controller包路径")) 
              .paths(PathSelectors.any())
              .build();
    }
 
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
              .title("我的接口文档")
              .description("我的接口文档")
              .version("2.0")
              .build();
    }
}

在上述代码中 @EnableKnife4j  注解开启了 Knife4j 在 Spring 项目中的支持，Docket 的配置与原生 Swagger 类似，用于指定要扫描的 API 接口范围和基本的文档信息，通过RequestHandlerSelectors.basePackage  确定了需要生成文档的 Controller 所在的包路径， PathSelectors.any()  表示包含所有的 API 路径。

启动项目查看 Knife4j UI

启动 Spring 项目后，访问http://localhost:8080/doc.html （默认端口为 8080，如果项目中配置了其他端口则相应替换），即可打开 Knife4j 的界面。在这个界面上，可以看到项目中所有被扫描到的 API 接口信息，包括接口名称、请求方法、请求参数、响应示例等，相比原生的Swagger UI，界面更加美观和易于操作，例如接口列表的展示更加清晰，搜索功能更加便捷等。

图示如下：

API 信息定制

在 Spring 的 Controller 类及方法中，使用Knife4j支持的 Swagger 注解来详细描述 API，例如：

@RestController
@RequestMapping("/api")
@Api(tags = "我的api")
public class UserController {
 
    @GetMapping("/users")
    @ApiOperation("用户列表")
    public List<User> getUsers() {
        // 实际业务逻辑代码，这里返回用户列表
        return userService.getUsers();
    }
}

• @Api 注解为整个 Controller 类添加一个标签，方便在 Knife4j UI 中对接口进行分类查看。
• @ApiOperation  注解详细描述了每个 API 方法的功能，该描述会在 Knife4j 界面中对应接口的详情页中展示，让使用者能够快速了解接口的用途。

再次启动项目查看：

成功显示更改信息。

总结

除了基础的配置和使用，还能通过以下方式扩展 Knife4j 的应用，在复杂的微服务架构中，利用其分组功能，为不同的微服务模块创建独立的 Docket  实例并设置不同 groupName ，使各模块 API 文档清晰区分，方便维护和查看。

对于 API 版本管理，除了在 URL 中体现版本，还可以结合自定义请求头，在 Knife4j 配置中精准匹配不同版本的接口路径，展示版本演进。

在安全方面，与多种认证方式深度集成，如 OAuth2 等，通过详细配置 securitySchemes  和 securityContexts ，在 API 文档中准确呈现复杂的认证流程和要求，帮助使用者更好地理解和接入安全的 API 服务。

总之，掌握在Spring中使用Knife4j的基本使用，能够高效地为项目生成友好且实用的API文档，提升整个项目开发过程中的沟通协作效率以及接口管理的便利性。

以上就是在Spring中使用Knife4j进行API文档生成与管理的操作方法的详细内容，更多关于Spring API文档生成与管理的资料请关注脚本之家其它相关文章！

最新评论