整合 Knife4j：提升接口调试效率

整合 Knife4j：提升接口调试效率

Knife4j 是什么？

Knife4j 是一个为 Java 项目生成和管理 API 文档的工具。实际上，它是 Swagger UI 的一个增强工具集，旨在让 Swagger 生成的 API 文档更优雅、更强大。

Knife4j 主要功能

• 美观的 UI：相比于原生 Swagger UI，Knife4j 提供了更加人性化和美观的界面设计。
• 丰富的文档交互功能：支持在线调试、请求参数动态输入、接口排序等。
• 个性化配置：可自定义 API 文档的界面风格，实现文档界面的个性化展示。

整合 Knife4j

添加依赖

<!-- 版本号统一管理 -->
    <properties>

        <!-- 依赖包版本 -->
		省略...        
        <knife4j.version>4.3.0</knife4j.version>
    </properties>
    
    <!-- 统一依赖管理 -->
    <dependencyManagement>
        <dependencies>
            省略...        

            <!-- knife4j（API 文档工具） -->
            <dependency>
                <groupId>com.github.xiaoymin</groupId>
                <artifactId>knife4j-openapi2-spring-boot-starter</artifactId>
                <version>${
    
    knife4j.version}</version>
            </dependency>
        </dependencies>
    </dependencyManagement>

添加配置类

@Configuration
@EnableSwagger2WebMvc
public class Knife4jConfig {
    
    

    @Bean("webApi")
    public Docket createApiDoc() {
    
    
        Docket docket = new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(buildApiInfo())
                // 分组名称
                .groupName("Web 前台接口")
                .select()
                // 这里指定 Controller 扫描包路径
                .apis(RequestHandlerSelectors.basePackage("com.qiheyehua.weblog.web.controller"))
                .paths(PathSelectors.any())
                .build();
        return docket;
    }
       @Bean("adminApi")
    public Docket createApiDoc() {
    
    
        Docket docket = new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(buildApiInfo())
                // 分组名称
                .groupName("Admin 后台接口")
                .select()
                // 这里指定 Controller 扫描包路径
                .apis(RequestHandlerSelectors.basePackage("com.qiheyehua.weblog.admin.controller"))
                .paths(PathSelectors.any())
                .build();
        return docket;
    }

    /**
     * 构建 API 信息
     * @return
     */
    private ApiInfo buildApiInfo() {
    
    
        return new ApiInfoBuilder()
                .title("Weblog 博客前台接口文档") // 标题
                .description("Weblog 是一款由 Spring Boot + Vue 3.2 + Vite 4.3 开发的前后端分离博客。") // 描述
                .termsOfServiceUrl("https://www.qiheyehua.com/") // API 服务条款
                .contact(new Contact("七禾页话", "https://www.qiheyehua.com", "[email protected]")) // 联系人
                .version("1.0") // 版本号
                .build();
    }
}

注意： RequestHandlerSelectors.basePackage("com.quanxiaoha.weblog.web.controller") 中的包路径，需要改成你实际的 controller 包路径，否则会导致接口扫描不到。

上述代码中，通过 @Configuration 指定了 Knife4jConfig 这个类为配置类，同时添加了 @EnableSwagger2WebMvc 注解，该注解作用是启用 Swagger2，定义了一个 Docket Bean 包含了 Swagger 相关的配置信息。

看看效果

完成上面配置后，重启项目，若控制台出现如下红线标注的日志，则表示 Knife4j 配置完成了：

浏览器访问路径 http://localhost:8080/doc.html , 就可以看到 api 管理界面了

给 controller 添加 Swagger 相关注解

痛点：目前在左侧显示的模块类名，以及接口名称都是代码中本身的英文，也许你当前调试中，能够清晰的知道哪个 controller 类、哪个接口都是干啥的，但是时间一长，接口多了起来，你就会一脸懵逼了，挨，这个 controller 是管理那块的功能的？

为了解决这个问题，Swagger 提供了相关的注解，可以标识模块名称，以及接口名称，并方便的展示在管理界面中。添加方式如下：

• @Api : 此注解作用于 controller 之上，用于描述相关职责；
• @ApiOperation : 此注解作用于接口上，用于描述接口干啥的；

添加完上面两个注解后，管理界面的效果图如下：

除上面两个注解外，我们还可以给入参对象添加 Swagger 相关注解，如下所示：

• @ApiModel : 此注解作用于实体类上，用于描述类；
• @ApiModelProperty : 此注解作用于字段上，用于描述字段；

最终效果如下：

生产环境如何屏蔽 Knife4j

很多时候，我们不想项目在生产环境中暴露出所有接口信息，只想在测试环境中联调使用，那么要如何屏蔽该功能呢?

Spring Boot Profile 特性

Profile 是 Spring Boot 中的一项特性，允许你在不同环境中使用不同的配置。这种机制使得我们可以轻松地在不同环境（如开发、测试和生产环境）中使用不同的配置参数。

@Profile 注解

你可以在配置类上添加 @Profile 注解，来控制 Knife4j 是否生效 。只有当指定的 Profile 处于激活状态时，该配置类才会被创建和被使用。代码如下：

@Configuration
@EnableSwagger2WebMvc
@Profile("dev") // 只在 dev 环境中开启
public class Knife4jConfig {
    
    
	省略...
}