后端开发中接口文档的维护一直是痛点——代码变了文档没更新、手动编写效率低、调用方总要问参数格式。OpenAPI 3.0 是当前 REST API 描述规范的标准springdoc-openapi是其 Spring Boot 实现继承并替代已停维的 SpringfoxKnife4j 在它之上提供更清爽的 UI 和更强的调试能力。本文从依赖配置到注解使用覆盖 springdoc Knife4j 的完整集成流程。一、springdoc-openapi 核心依赖与配置1.1 导入依赖springfox 需要两个包swagger2 swagger-uispringdoc 一个包即含 JSON 端点 UIdependencygroupIdorg.springdoc/groupIdartifactIdspringdoc-openapi-starter-webmvc-ui/artifactIdversion2.6.0/version/dependencySpring Boot 3.x / Jakarta / JDK 17 环境使用此坐标。若仍是 Spring Boot 2.x / javax改为springdoc-openapi-ui1.8.x。1.2 配置类springdoc 无需EnableSwagger2注解引入依赖即自动配置。用OpenAPIBean 代替 Springfox 的DocketConfigurationpublicclassOpenApiConfig{BeanpublicOpenAPIcustomOpenApi(){returnnewOpenAPI().info(newInfo().title(平台管理 API 文档).description(平台管理服务 api).version(1.0.0).contact(newContact().name(漫步阡陌))).components(newComponents().addSecuritySchemes(bearer-key,newSecurityScheme().type(SecurityScheme.Type.HTTP).scheme(bearer).bearerFormat(JWT)));}}关键说明Info等同于 Springfox 的ApiInfo设置标题、描述、版本、联系人SecurityScheme声明全局安全方案JWT token替代 Springfox 中globalOperationParameters手动添加 Header 参数的做法包扫描通过RequestMapping自动发现无需显式配置basePackage若需多分组见下文1.3 多 Docket 分组微服务中前后台接口需分开展现时用GroupedOpenApiConfigurationpublicclassGroupedOpenApiConfig{BeanpublicGroupedOpenApiadminApi(){returnGroupedOpenApi.builder().group(admin).displayName(后台管理接口).pathsToMatch(/admin/**).build();}BeanpublicGroupedOpenApiappApi(){returnGroupedOpenApi.builder().group(app).displayName(移动端接口).pathsToMatch(/app/**).build();}}1.4 跨模块引用配置配置类置于公共模块时业务模块通过ComponentScan引入ConfigurationComponentScan(com.heima.common.openapi)publicclassOpenApiScanConfig{}1.5 访问地址启动后端点说明/v3/api-docsOpenAPI 3.0 规范 JSON/swagger-ui.htmlSwagger UI 官方页面/doc.htmlKnife4j 增强 UI需加 Knife4j 依赖二、常用注解springdoc 使用io.swagger.v3.oas.annotations包与 Springfox 的io.swagger.annotations不同。Springfox 旧注解springdoc 新注解作用ApiTag描述 Controller 类别ApiOperationOperation描述接口用途ApiParamParameter描述单个参数ApiImplicitParam(s)Parameters/Parameter描述请求参数列表ApiModelSchema描述实体类ApiModelPropertySchema描述实体字段ApiIgnoreHidden隐藏接口或参数ApiResponse/ApiResponsesApiResponse同包描述响应信息2.1 注解实例RestControllerRequestMapping(/api/v1/channel)Tag(name频道管理 API)publicclassWmChannelController{AutowiredprivateIWmChannelServicewMChannelService;PostMapping(/list)Operation(summary根据名称模糊查询分页列表,description频道名称模糊匹配)publicResponseResultlistByName(RequestBodyParameter(description查询对象,requiredtrue)ChannelDtodto){returnwMChannelService.listByName(dto);}}DTO 实体DataEqualsAndHashCode(callSupertrue)publicclassChannelDtoextendsPageRequestDto{Schema(description频道名称)privateStringname;}2.2 注解对照速查表用Schema同时替代了 Springfox 的ApiModel类级和ApiModelProperty字段级一个注解完成Schema(description频道查询参数)publicclassChannelDto{Schema(description频道名称,example科技)privateStringname;Schema(description当前页码,minimum1,defaultValue1)privateIntegerpage;}三、Knife4j 整合Knife4j 为 springdoc 提供了专属启动器不再依赖 Swagger UI3.1 导入依赖dependencygroupIdcom.github.xiaoymin/groupIdartifactIdknife4j-openapi3-spring-boot-starter/artifactIdversion4.5.0/version/dependencyspringdoc Knife4j 用此坐标OpenAPI 3 版旧版 Springfox Knife4j 用的是knife4j-spring-boot-starter两者不混用。3.2 配置文件引入该依赖后Knife4j 自动接入 springdoc 的 OpenAPI 端点:springdoc:swagger-ui:path:/doc.htmltags-sorter:alphaoperations-sorter:alphaapi-docs:path:/v3/api-docsknife4j:enable:truesetting:language:zh_cnswagger-model-name:应用名称3.3 访问与鉴权启动后访问http://localhost:8080/doc.html。生产环境防暴露knife4j:basic:enable:trueusername:adminpassword:adminproduction:true# 生产模式禁止展示接口enable:true四、Springfox → springdoc 迁移要点对比项Springfox (Swagger 2)springdoc (OpenAPI 3)依赖包springfox-swagger2 springfox-swagger-uispringdoc-openapi-starter-webmvc-ui启用注解EnableSwagger2无需注解自动配置核心 BeanDocketOpenAPI/GroupedOpenApi注解包io.swagger.annotations.*io.swagger.v3.oas.annotations.*Spring Boot 2.6 兼容需spring.mvc.pathmatch.matching-strategyant-path-matcher原生兼容WebFlux / 函数式端点支持弱原生支持维护状态已停维活跃维护API 规范/v2/api-docs/v3/api-docs小结组件职责springdoc-openapi扫描注解生成 OpenAPI 3.0 规范 JSONKnife4j增强 UI 渲染 调试面板/doc.html新项目直接选 springdoc Knife4j注解用Tag、Operation、Schema零额外配置即可出文档迁移成本也不高。文章结束喜欢就给个一键三连吧你的肯定是我最大的动力点赞上一千我就是脑瘫也出下章。