Spring Boot 整合 Swagger2 和 Knife4j实现接口文档与可视化调试

文章目录

- 一、Swagger2（Springfox）核心依赖与配置
- - [1.1 导入依赖](#1.1 导入依赖)
  - [1.2 配置类](#1.2 配置类)
  - [1.3 Spring Boot 2.6+ 兼容处理](#1.3 Spring Boot 2.6+ 兼容处理)
  - [1.4 跨模块引用配置](#1.4 跨模块引用配置)
- 二、常用注解
- - [2.1 注解实例](#2.1 注解实例)
- [三、Knife4j 整合](#三、Knife4j 整合)
- - [3.1 导入依赖](#3.1 导入依赖)
  - [3.2 配置文件](#3.2 配置文件)
  - [3.3 访问与鉴权](#3.3 访问与鉴权)
- 总结

后端开发中接口文档的维护一直是痛点------代码变了文档没更新、手动编写效率低、调用方总要问参数格式。Swagger2（基于 Springfox 实现）通过注解自动生成 API 文档，Knife4j 在其基础上提供更清爽的 UI 和更强的调试能力。本文从依赖配置到注解使用，覆盖 Swagger2 + Knife4j 的完整集成流程。

一、Swagger2（Springfox）核心依赖与配置

1.1 导入依赖

xml 复制代码

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

1.2 配置类

java 复制代码

@Configuration
@EnableSwagger2
public class SwaggerConfiguration {

    @Bean
    public Docket buildDocket() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(buildApiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.mbqm"))
                .paths(PathSelectors.any())
                .build()
                .globalOperationParameters(getParameterList());
    }

    private ApiInfo buildApiInfo() {
        return new ApiInfoBuilder()
                .title("平台管理 API 文档")
                .description("平台管理服务 api")
                .contact(new Contact("小Ti客栈", "", ""))
                .version("1.0.0")
                .build();
    }

    private List<Parameter> getParameterList() {
        ParameterBuilder builder = new ParameterBuilder();
        List<Parameter> params = new ArrayList<>();
        params.add(builder
                .name("Authorization")
                .description("token 认证")
                .modelRef(new ModelRef("string"))
                .parameterType("header")
                .required(false)
                .build());
        return params;
    }
}

关键说明：

RequestHandlerSelectors.basePackage("com.mbqm") 指定扫描的 Controller 包路径，微服务中每个服务各配自己的包；
globalOperationParameters 用于全局添加请求头参数（如 token），避免每个接口重复定义；
buildApiInfo 配置文档标题、描述、联系人、版本号。

1.3 Spring Boot 2.6+ 兼容处理

Spring Boot 2.6 起默认路径匹配从 AntPathMatcher 切换为 PathPatternParser，与 Springfox 不兼容，需回退：

yaml 复制代码

spring:
  mvc:
    pathmatch:
      matching-strategy: ant-path-matcher

1.4 跨模块引用配置

如果 Swagger 配置类放在公共模块（如 common），业务模块需通过 @ComponentScan 引入：

java 复制代码

@Configuration
@ComponentScan("com.heima.common.swagger")
public class SwaggerConfig {
}

启动后访问 http://localhost:8080/swagger-ui.html 即可看到文档页面。

二、常用注解

注解	作用位置	作用
`@Api`	Controller 类	描述模块作用
`@ApiOperation`	接口方法	描述接口用途
`@ApiImplicitParam`	接口方法	描述单个请求参数
`@ApiImplicitParams`	接口方法	描述多个请求参数
`@ApiParam`	方法参数	描述参数的约束信息
`@ApiModel`	请求/响应实体类	描述实体
`@ApiModelProperty`	实体字段	描述字段含义
`@ApiIgnore`	方法或类	忽略该接口，不出现在文档中
`@ApiResponse`	接口方法	描述响应信息
`@ApiResponses`	接口方法	描述整体响应

2.1 注解实例

java 复制代码

@RestController
@RequestMapping("/api/v1/channel")
@Api(tags = "频道管理 API")
public class WmChannelController {

    @Autowired
    private IWmChannelService wMChannelService;

    @PostMapping("/list")
    @ApiOperation(value = "根据名称模糊查询分页列表", notes = "频道名称模糊匹配")
    @ApiImplicitParam(name = "dto", value = "查询对象", required = true, dataType = "ChannelDto")
    public ResponseResult listByName(@RequestBody ChannelDto dto) {
        return wMChannelService.listByName(dto);
    }
}

DTO 实体：

java 复制代码

@Data
@EqualsAndHashCode(callSuper = true)
public class ChannelDto extends PageRequestDto {

    @ApiModelProperty(value = "频道名称")
    private String name;
}

三、Knife4j 整合

Knife4j 是 Swagger 的增强 UI 工具包，界面更现代，支持离线文档、全局参数调试、请求缓存等。

3.1 导入依赖

Swagger2 版本使用 Knife4j 专用启动器：

xml 复制代码

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

Swagger 原有的配置类无需改动，Knife4j 自动兼容。

3.2 配置文件

yaml 复制代码

knife4j:
  enable: true
  setting:
    language: zh_cn
    swagger-model-name: 应用名称

3.3 访问与鉴权

启动后访问 http://localhost:8080/doc.html，相比原生 Swagger UI：

接口分组左侧树形展示，层次更清晰；
右侧参数调试支持全局参数（如 token）；
支持请求缓存，同一接口多次调试不必重复填参数。

生产环境关闭文档暴露：

yaml 复制代码

knife4j:
  basic:
    enable: true
    username: admin
    password: admin
  production: true
  enable: true

开启 basic 鉴权后，访问 /doc.html 需输入用户名密码；production: true 使接口列表不可见，防止生产环境泄露。

总结

组件	职责
springfox-swagger2	通过注解生成 Swagger2 规范 JSON
springfox-swagger-ui	Swagger 原生 UI（/swagger-ui.html）
knife4j	增强 UI + 更多调试功能（/doc.html）

开发阶段用 Knife4j 提升调试效率，生产环境开启 production=true + basic 鉴权防暴露。需要注意的是 Springfox 已停维，新项目建议直接使用 springdoc-openapi（OpenAPI 3），迁移成本不高。

文章结束，喜欢就给个一键三连吧，你的肯定是我最大的动力，点赞上一千我就是脑瘫也出下章。