Spring Boot 集成 Springdoc-OpenAPI 与 Knife4j实现接口文档与可视化调试

后端开发中接口文档的维护一直是痛点------代码变了文档没更新、手动编写效率低、调用方总要问参数格式。

OpenAPI 3.0 是当前 REST API 描述规范的标准，springdoc-openapi 是其 Spring Boot 实现（继承并替代已停维的 Springfox），Knife4j 在它之上提供更清爽的 UI 和更强的调试能力。

本文从依赖配置到注解使用，覆盖 springdoc + Knife4j 的完整集成流程。

一、springdoc-openapi 核心依赖与配置

1.1 导入依赖

springfox 需要两个包（swagger2 + swagger-ui），springdoc 一个包即含 JSON 端点 + UI：

xml 复制代码

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
    <version>2.6.0</version>
</dependency>

Spring Boot 3.x / Jakarta / JDK 17+ 环境使用此坐标。若仍是 Spring Boot 2.x / javax，改为 springdoc-openapi-ui（1.8.x）。

1.2 配置类

springdoc 无需 @EnableSwagger2 注解，引入依赖即自动配置。用 OpenAPI Bean 代替 Springfox 的 Docket：

java 复制代码

@Configuration
public class OpenApiConfig {

    @Bean
    public OpenAPI customOpenApi() {
        return new OpenAPI()
                .info(new Info()
                        .title("平台管理 API 文档")
                        .description("平台管理服务 api")
                        .version("1.0.0")
                        .contact(new Contact().name("漫步阡陌")))
                .components(new Components()
                        .addSecuritySchemes("bearer-key",
                                new SecurityScheme()
                                        .type(SecurityScheme.Type.HTTP)
                                        .scheme("bearer")
                                        .bearerFormat("JWT")));
    }
}

关键说明：

Info 等同于 Springfox 的 ApiInfo，设置标题、描述、版本、联系人；
SecurityScheme 声明全局安全方案（JWT token），替代 Springfox 中 globalOperationParameters 手动添加 Header 参数的做法；
包扫描通过 @RequestMapping 自动发现，无需显式配置 basePackage（若需多分组见下文）；

1.3 多 Docket 分组

微服务中前后台接口需分开展现时，用 @GroupedOpenApi：

java 复制代码

@Configuration
public class GroupedOpenApiConfig {

    @Bean
    public GroupedOpenApi adminApi() {
        return GroupedOpenApi.builder()
                .group("admin")
                .displayName("后台管理接口")
                .pathsToMatch("/admin/**")
                .build();
    }

    @Bean
    public GroupedOpenApi appApi() {
        return GroupedOpenApi.builder()
                .group("app")
                .displayName("移动端接口")
                .pathsToMatch("/app/**")
                .build();
    }
}

1.4 跨模块引用配置

配置类置于公共模块时，业务模块通过 @ComponentScan 引入：

java 复制代码

@Configuration
@ComponentScan("com.heima.common.openapi")
public class OpenApiScanConfig {
}

1.5 访问地址

启动后：

端点	说明
`/v3/api-docs`	OpenAPI 3.0 规范 JSON
`/swagger-ui.html`	Swagger UI 官方页面
`/doc.html`	Knife4j 增强 UI（需加 Knife4j 依赖）

二、常用注解

springdoc 使用 io.swagger.v3.oas.annotations 包，与 Springfox 的 io.swagger.annotations 不同。

Springfox 旧注解	springdoc 新注解	作用
`@Api`	`@Tag`	描述 Controller 类别
`@ApiOperation`	`@Operation`	描述接口用途
`@ApiParam`	`@Parameter`	描述单个参数
`@ApiImplicitParam(s)`	`@Parameters` / `@Parameter`	描述请求参数列表
`@ApiModel`	`@Schema`	描述实体类
`@ApiModelProperty`	`@Schema`	描述实体字段
`@ApiIgnore`	`@Hidden`	隐藏接口或参数
`@ApiResponse` / `@ApiResponses`	`@ApiResponse`（同包）	描述响应信息

2.1 注解实例

java 复制代码

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

    @Autowired
    private IWmChannelService wMChannelService;

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

DTO 实体：

java 复制代码

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

    @Schema(description = "频道名称")
    private String name;
}

2.2 注解对照速查表

用 @Schema 同时替代了 Springfox 的 @ApiModel（类级）和 @ApiModelProperty（字段级），一个注解完成：

java 复制代码

@Schema(description = "频道查询参数")
public class ChannelDto {

    @Schema(description = "频道名称", example = "科技")
    private String name;

    @Schema(description = "当前页码", minimum = "1", defaultValue = "1")
    private Integer page;
}

三、Knife4j 整合

Knife4j 为 springdoc 提供了专属启动器，不再依赖 Swagger UI：

3.1 导入依赖

xml 复制代码

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

springdoc + Knife4j 用此坐标（OpenAPI 3 版）；旧版 Springfox + Knife4j 用的是 knife4j-spring-boot-starter，两者不混用。

3.2 配置文件

引入该依赖后，Knife4j 自动接入 springdoc 的 OpenAPI 端点:

yaml 复制代码

springdoc:
  swagger-ui:
    path: /doc.html
    tags-sorter: alpha
    operations-sorter: alpha
  api-docs:
    path: /v3/api-docs

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

3.3 访问与鉴权

启动后访问 http://localhost:8080/doc.html。

生产环境防暴露：

yaml 复制代码

knife4j:
  basic:
    enable: true
    username: admin
    password: admin
  production: true         # 生产模式，禁止展示接口
  enable: true

四、Springfox → springdoc 迁移要点

对比项	Springfox (Swagger 2)	springdoc (OpenAPI 3)
依赖包	springfox-swagger2 + springfox-swagger-ui	springdoc-openapi-starter-webmvc-ui
启用注解	`@EnableSwagger2`	无需注解，自动配置
核心 Bean	`Docket`	`OpenAPI` / `GroupedOpenApi`
注解包	`io.swagger.annotations.*`	`io.swagger.v3.oas.annotations.*`
Spring Boot 2.6+ 兼容	需 `spring.mvc.pathmatch.matching-strategy=ant-path-matcher`	原生兼容
WebFlux / 函数式端点	支持弱	原生支持
维护状态	已停维	活跃维护
API 规范	`/v2/api-docs`	`/v3/api-docs`

小结

组件	职责
springdoc-openapi	扫描注解生成 OpenAPI 3.0 规范 JSON
Knife4j	增强 UI 渲染 + 调试面板（/doc.html）

新项目直接选 springdoc + Knife4j，注解用 @Tag、@Operation、@Schema，零额外配置即可出文档，迁移成本也不高。

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