目录描述---痛点Springfox对比springdoc-openapi1. 成熟度和维护性2. 依赖和配置3. 注解和使用方式4. 特性和扩展性应用目录结构pom文件新增测试controllerStaffControllerYUserController启动测试看下验证swaggeryml中添加配置配置OpenApiConfig验证配置swagger验证接口无参有参优化下界面openapi添加jar包验证结果描述---痛点我们项目中很多时候都会用到swagger swagger2 (以下全部称swagger)当我们配置Springboot集成swagger时要选对应的版本才可以不然就会报各种错误版本不匹配或高或低例如Application run failedorg.springframework.context.ApplicationContextException: Failed to start bean documentationPluginsBootstrapper; nested exception is java.lang.NullPointerExceptionjava.lang.IllegalStateException: Cannot set parent bean factory to self等等。就会很麻烦或者是当我们去升级spring-boot的时候 也会遇到这些问题这时我们可以尝试更改用springdoc-openapi-ui取替代swaggerspringdoc-openapi-ui中间已经包含了swagger也就是说使用springdoc-openapi-ui是可以替代的。他的配置相对的话就比较简单配置起来也不会很麻烦我们看下是如何配置Springfox对比springdoc-openapi在该片中我用的是springdoc-openapi相对来说更加适合于我简单轻量配置更少一些还有一点就是直接更喜欢Springfox和springdoc-openapi都是用于在Spring Boot应用程序中集成OpenAPI和Swagger UI的库。1. 成熟度和维护性- Springfox是一个相对成熟和广泛使用的库已经存在一段时间并且有一个活跃的社区进行维护和更新。- springdoc-openapi是相对较新的库但也在不断发展和更新它的目标是提供更简单、更轻量级的集成方式。2. 依赖和配置- Springfox通常需要引入springfox-boot-starter等相关依赖并进行一些配置以便生成和展示Swagger文档。- springdoc-openapi通常只需要引入springdoc-openapi-ui依赖并且不需要太多的配置即可生成和展示OpenAPI文档。3. 注解和使用方式- Springfox使用Api、ApiOperation等注解来定义API文档并提供了一些配置选项来自定义文档生成。- springdoc-openapi使用io.swagger.v3.oas.annotations包下的注解来定义API文档它遵循OpenAPI规范并提供了一些额外的注解来进行更细粒度的控制。4. 特性和扩展性- Springfox提供了一些额外的特性和扩展如支持Spring Security集成、自定义UI主题等。- springdoc-openapi也提供了一些特性和扩展如支持Spring Security集成、自定义UI主题等但可能相对较少。如何选择使用Springfox还是springdoc-openapi如果你需要更成熟、功能更丰富的库并且对配置和注解的灵活性有更高的要求那么Springfox可能是一个不错的选择。如果你更倾向于简单、轻量级的集成方式并且遵循OpenAPI规范的优先级更高那么springdoc-openapi可能更适合你。应用目录结构pom文件我用的springboot是2.7.10还是比较新的。只需要引入springdoc-openapi-ui这一个即可parent groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-parent/artifactId version2.7.10/version relativePath/ !-- lookup parent from repository -- /parent !--Springfox/swagger迁移springdoc-openapi springdoc-openapi最新版本和springboot应用集成-- dependency groupIdorg.springdoc/groupId artifactIdspringdoc-openapi-ui/artifactId version1.5.12/version /dependency !-- 可以不引入 -- dependency groupIdorg.reflections/groupId artifactIdreflections/artifactId version0.9.12/version /dependency修改时间 2025年4月15日13:20:24 BEGINspringboot3.2.5版本配置dependency groupIdorg.reflections/groupId artifactIdreflections/artifactId version${reflections.version}/version exclusions exclusion artifactIdjavassist/artifactId groupIdorg.javassist/groupId /exclusion /exclusions /dependency dependency groupIdorg.springdoc/groupId artifactIdspringdoc-openapi-starter-webmvc-ui/artifactId version2.3.0/version /dependency dependency groupIdcom.github.xiaoymin/groupId artifactIdknife4j-openapi3-spring-boot-starter/artifactId version4.4.0/version exclusions exclusion groupIdorg.webjars/groupId artifactIdswagger-ui/artifactId /exclusion /exclusions /dependency !--添加Knife4j依赖-- dependency groupIdcom.github.xiaoymin/groupId artifactIdknife4j-openapi3-jakarta-spring-boot-starter/artifactId version4.5.0/version /dependency不需要yml中添加配置添加一个properties即可 knife4j.enabletrue knife4j.base-packagecn.axa.provider knife4j.exclude-path/error knife4j.setting.path/provider/doc.html knife4j.setting.titleAPI?? knife4j.setting.descriptionAPI?? knife4j.setting.version1.0.0 knife4j.setting.license.nameApache 2.0修改时间 2025年4月15日13:20:36 END修改时间 2026年10月15日09:33:00 BEGINspringboot3.5.16版本配置需要更改的只有springdoc-openapi-starter-webmvc-ui版本2.8.13其它无需变更groupIdorg.springdoc/groupId artifactIdspringdoc-openapi-starter-webmvc-ui/artifactId version2.8.13/version exclusions修改时间 2026年10月15日09:38:00 END新增测试controllerTag注解用于指定相关测试controller的APIStaffControllerpackage com.yun.greedy.modules.staff.controller; import com.yun.greedy.modules.staff.entity.Staff; import com.yun.greedy.modules.staff.service.StaffService; import io.swagger.v3.oas.annotations.tags.Tag; import lombok.extern.slf4j.Slf4j; import org.springframework.beans.factory.annotation.Autowired; import org.springframework.web.bind.annotation.GetMapping; import org.springframework.web.bind.annotation.RequestMapping; import org.springframework.web.bind.annotation.RestController; import java.util.List; /** * p * 前端控制器 * /p * * author ex_yangqiusheng * since 2023-06-29 */ Slf4j RestController Tag(name StaffController测试数据, description 测试数据验证) RequestMapping(/staff) public class StaffController { Autowired private StaffService staffService; GetMapping(/list) public ListStaff list() { ListStaff list staffService.getBaseMapper().selectList(null); log.info(结果值打印--------------------); list.forEach(System.out::println); return list; } }YUserControllerpackage com.yun.greedy.modules.yuser.controller; import com.baomidou.mybatisplus.core.conditions.query.QueryWrapper; import com.yun.greedy.modules.yuser.entity.YUser; import com.yun.greedy.modules.yuser.service.YUserService; import io.swagger.v3.oas.annotations.tags.Tag; import org.springframework.beans.factory.annotation.Autowired; import org.springframework.boot.configurationprocessor.json.JSONException; import org.springframework.boot.configurationprocessor.json.JSONObject; import org.springframework.web.bind.annotation.*; import java.util.List; Tag(name YUserController账户操作, description 账户相关信息) RequestMapping(/YUser) RestController public class YUserController { Autowired private YUserService yUserService; GetMapping(value /queryYUserById) public YUser queryYUserId(Long yId){ YUser yUser yUserService.getById(yId); return yUser; } GetMapping(value /queryYUserByName) public ListYUser queryYUserName(String name){ ListYUser list yUserService.getBaseMapper().selectList(new QueryWrapperYUser().eq(y_name, name)); return list; } GetMapping(value /searchYUser) public YUser searchYUser(Long yId,String yName){ YUser yUser YUser.builder().yId(yId).yName(yName).build(); return yUser; } PostMapping(value /postYUser) public YUser queryYUser(RequestBody JSONObject jsonObject) throws JSONException { long yId jsonObject.getLong(yId); String yName jsonObject.getString(yName); YUser yUser YUser.builder().yId(yId).yName(yName).build(); return yUser; } }启动测试看下启动完成如果不知道如何搭建新项目的可以借鉴看下这篇文章从零到一新建项目https://blog.csdn.net/weixin_59383491/article/details/132596733验证swaggerhttp://localhost:8088/swagger-ui/index.html浏览器输入这个地址显示这个页面说明swagger正常。yml中添加配置springdoc: api-docs: #是否开启文档功能默认为true可不配置 enabled: true swagger-ui: # 访问ip:host/api可直接访问Swagger springdoc path: /api配置OpenApiConfigpackage com.yun.greedy.config; import io.swagger.v3.oas.annotations.OpenAPIDefinition; import io.swagger.v3.oas.annotations.enums.SecuritySchemeIn; import io.swagger.v3.oas.annotations.enums.SecuritySchemeType; import io.swagger.v3.oas.annotations.security.SecurityRequirement; import io.swagger.v3.oas.annotations.security.SecurityScheme; import io.swagger.v3.oas.models.OpenAPI; import io.swagger.v3.oas.models.info.Contact; import io.swagger.v3.oas.models.info.Info; import io.swagger.v3.oas.models.info.License; import io.swagger.v3.oas.models.tags.Tag; import org.reflections.Reflections; import org.reflections.scanners.SubTypesScanner; import org.reflections.util.ConfigurationBuilder; import org.springdoc.core.GroupedOpenApi; import org.springframework.context.annotation.Bean; import org.springframework.context.annotation.Configuration; import org.springframework.web.bind.annotation.RestController; import java.util.Set; /** * 这里的OpenAPIDefinition 和SecurityScheme都是springdoc注解主要声明API信息标题、版本、许可证、安全性、服务器、标签、安全性和拓展文档信息。 * 配置jwt时SecurityScheme(type SecuritySchemeType.HTTP, name “JWT”, scheme “bearer”, in SecuritySchemeIn.HEADER).scheme 还支持basic。 * 具体可查看官网文档: https://springdoc.org/index.html */ OpenAPIDefinition(security SecurityRequirement(name Authorization)) SecurityScheme(type SecuritySchemeType.APIKEY, name Authorization, scheme Authorization, in SecuritySchemeIn.HEADER) Configuration public class OpenApiConfig { private String title 寒舞;//标题 private String group group;//分组名称 private String description 被你捧做神明的人怎会低头看尘埃里的你;//简介 private String version ver_1.0.0;//版本 private String termsOfService https://blog.csdn.net/weixin_59383491;//服务Url private String contactName 一百减一是零;//作者 Bean public OpenAPI springOpenAPI() { return new OpenAPI() .info(getInfo()); } public Info getInfo() { return new Info() .title(title) .description(description) .version(version) .termsOfService(termsOfService) .license(buildLicense()) .contact(buildContact()); } public Contact buildContact() { return new Contact() .name(contactName) .email(517306474qq.com)//Your API Contact Email .url(https://blog.csdn.net/weixin_59383491);//Your API Contact URL } public License buildLicense() { return new License() .name(APACHE LICENSE, VERSION 2.0)//许可证 .url(https://www.apache.org/licenses/LICENSE-2.0.html); } Bean public GroupedOpenApi publicApi() { return GroupedOpenApi.builder() .group(group) .pathsToMatch(/YUser/**,/staff/**)//API路径不是类路径 //这里是添加对应标签 /*.addOpenApiCustomiser(openApi - { Tag staffTag new Tag(); staffTag.setName(myController);//标签名称 staffTag.setDescription(验证一下所有Controller);//描述 // 指定某个包中的所有controller String packagePath com.yun.greedy.modules.staff.controller; SetClass? controllerClasses getControllerClasses(packagePath); for (Class? controllerClass : controllerClasses) { String controllerName controllerClass.getSimpleName(); staffTag.addExtension(x-controller- controllerName, controllerClass.getName()); } // 指定单独的controller // String controllerName YourControllerName; // Class? controllerClass getControllerClass(packagePath, controllerName); // if (controllerClass ! null) { // staffTag.addExtension(x-controller- controllerName, controllerClass.getName()); // } if (null ! openApi.getTags()){ openApi.getTags().add(staffTag); } else { openApi.addTagsItem(staffTag);//添加标签 } })*/ .build(); } //显式地配置扫描器 private Reflections reflectionsConf(String packagePath){ return new Reflections(new ConfigurationBuilder() .forPackages(packagePath) .addScanners(new SubTypesScanner())); } // 获取某个包中的所有controller类 private SetClass? getControllerClasses(String packagePath) { Reflections reflections reflectionsConf(packagePath); return reflections.getTypesAnnotatedWith(RestController.class); } // 获取单独的controller类 private Class? getControllerClass(String packagePath, String controllerName) { Reflections reflections reflectionsConf(packagePath); SetClass? controllerClasses reflections.getTypesAnnotatedWith(RestController.class); for (Class? controllerClass : controllerClasses) { if (controllerClass.getSimpleName().equals(controllerName)) { return controllerClass; } } return null; } }验证配置swaggerhttp://localhost:8088/api重启应用输入此地址展示以下页面显示配置成功验证接口无参try一下执行结果有参执行结果现在看起来是没有问题的配置展示执行结果都是正常但是这个页面看着削为有点简陋优化下界面openapi添加jar包!--美化swagger-- dependency groupIdcom.github.xiaoymin/groupId artifactIdknife4j-springdoc-ui/artifactId version3.0.3/version /dependencyhttp://localhost:8088/doc.html重启应用输入地址展示以下界面就可以了。验证结果OK执行成功到此就算是完成了