Knife4j 接口文档使用流程分析

Knife4j 接口文档使用是我们常用的工具，今天我们在springBoot框架中分享一下。

Knife4j 基于 Swagger 规范开发，本质上是对 Swagger 的二次封装，通过优化 UI 和扩展功能提升开发体验‌12。例如，Knife4j 的前身是 swagger-bootstrap-ui，专为 Java 开发者设计‌。

Swagger 作为通用规范（如 OpenAPI），适用于多语言场景；而 Knife4j 聚焦于 Java 生态，解决 Spring Boot/Cloud 项目中 Swagger 的易用性问题‌。

Knife4j 的版本与 Swagger 规范紧密关联。例如，Knife4j 的 OpenAPI 3 版本基于 SpringDoc 实现，兼容 Spring Boot 3，而旧版本则基于原生 Swagger（OpenAPI 2)

1、pom文件引用

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

2、Swagger + Knife4j 配置类

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration
@EnableSwagger2
@EnableKnife4j  // 启用 Knife4j 增强功能
public class SwaggerConfig {

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                // 指定 Controller 扫描包路径（根据实际项目调整）
                .apis(RequestHandlerSelectors.basePackage("com.example.controller"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("API 文档标题")
                .description("API 接口详细描述")
                .version("1.0.0")
                .contact(new Contact("开发者名称", "https://example.com", "[e-mail]"))
                .build();
    }
}

3、调整 Spring Boot 配置

application.yml 中添加以下配置，优化文档展示及避免静态资源拦截：

knife4j:
  enable: true  # 开启 Knife4j（默认已开启，可省略）
  production: false  # 生产环境建议设为 true 以禁用文档

spring:
  mvc:
    pathmatch:
      matching-strategy: ant_path_matcher  # 解决 Spring Boot 2.6+ 与 Swagger 兼容性问题

如果部署2.6+版本，那么需要引用Swagger jar,比如：

       <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.7.0</version>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.7.0</version>
        </dependency>

4、启动后访问

http://localhost:8080/doc.html

• 默认 UI 路径‌：/doc.html（Knife4j 增强文档）
• ‌原生 Swagger 路径‌：/swagger-ui.html

5、生产环境屏蔽

knife4j:
  production: true  # 禁用文档访问

6、使用注意：

1）请求和返回对象一定是自定义的POJO，否则文档上不显示参数详细信息。如果是继承了map或者其他原生的类，就显示不出来信息。

7、

8、