SpringBoot整合Knife4j实现接口文档自动生成的最佳实践

写接口文档有多烦人？做过前后端联调的朋友都懂。手写吧，费时费力还容易跟代码对不上号；不写吧，前端同事跑来问接口参数，一天能打断你八回。Knife4j 这玩意儿就是来终结这种痛苦的——只要加几个注解，接口文档自动生成，还附带在线调试功能。

一、为什么选 Knife4j

目前市面上做接口文档的方案不少，但从实际体验来看，Knife4j 对国内开发者确实很友好。核心优势在于两点：一是 UI 界面做了汉化，看着舒服；二是它不仅仅是文档展示工具，在线调试功能体验比原生的 Swagger UI 更流畅。

拿它和 Swagger UI、手写文档对比一下，差别就很直观了：Knife4j 的支持度更完善，Swagger UI 虽然也能在线调试，但界面是英文的，手写文档就更不用说了，维护成本高到离谱。代码上，Knife4j 和 Swagger 都是走注解方式，侵入性很低，但 Knife4j 的维护成本几乎为零——因为文档跟代码是自动同步的。

二、集成 Knife4j

1. 引入依赖

将下面这个依赖加到 pom.xml 里，版本号建议用稳定版：

    com.github.xiaoymin
    knife4j-spring-boot-starter
    3.0.3

2. 配置

然后在 application.yml 或 application.properties 里补充这几项配置，确保 Spring 的路径匹配方式兼容 Knife4j：

spring:
  mvc:
    pathmatch:
      matching-strategy: ant_path_matcher
knife4j:
  enable: true
  setting:
    language: zh-CN
    enable-swagger-models: true
    enable-document-manage: true
    swagger-model-order: 1

3. 配置类

创建一个配置类，注册一个 Docket Bean。这里的关键是指定好你想扫描的控制器包路径，比如下面这个例子扫的是 com.zhang 包下的所有控制器：

@Configuration
@EnableKnife4j
public class Knife4jConfig {

    @Bean
    public Docket defaultApi() {
        return new Docket(DocumentationType.SWAGGER_2)
            .apiInfo(apiInfo())
            .select()
            .apis(RequestHandlerSelectors.basePackage("com.zhang"))
            .paths(PathSelectors.any())
            .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
            .title("秒杀系统接口文档")
            .description("电商秒杀系统 RESTful API")
            .version("V1.0")
            .contact(new Contact("张政", "", ""))
            .build();
    }
}

做完上面这三步，项目启动后访问 http://localhost:9090/doc.html，就能看到自动生成的接口文档页面了。页面里不光能看到每个接口的请求方式、参数说明、返回示例，还能直接点「调试」按钮在线测试接口，省去了来回切换工具的痛苦。