目录

描述---痛点

Springfox对比springdoc-openapi

1. 成熟度和维护性：

2. 依赖和配置：

3. 注解和使用方式：

4. 特性和扩展性：

应用目录结构

pom文件

新增测试controller

StaffController

YUserController

启动测试看下

验证swagger

yml中添加配置

配置OpenApiConfig 

验证配置swagger

验证接口

无参

有参

优化下界面openapi

添加jar包

 验证结果

描述---痛点

我们项目中很多时候都会用到swagger swagger2 (以下全部称swagger)

当我们配置Springboot集成swagger时，要选对应的版本才可以，不然就会报各种错误，版本不匹配，或高或低

例如

Application run failed

org.springframework.context.ApplicationContextException: Failed to start bean 'documentationPluginsBootstrapper'; nested exception is java.lang.NullPointerException

java.lang.IllegalStateException: Cannot set parent bean factory to self

等等。就会很麻烦

或者是当我们去升级spring-boot的时候  也会遇到这些问题，这时我们可以尝试更改用springdoc-openapi-ui取替代swagger

springdoc-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> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-parent</artifactId> <version>2.7.10</version> <relativePath/> <!-- lookup parent from repository --> </parent><!--Springfox/swagger迁移springdoc-openapi & springdoc-openapi最新版本和springboot应用集成--> <dependency> <groupId>org.springdoc</groupId> <artifactId>springdoc-openapi-ui</artifactId> <version>1.5.12</version> </dependency><!-- 可以不引入 --> <dependency> <groupId>org.reflections</groupId> <artifactId>reflections</artifactId> <version>0.9.12</version> </dependency>

新增测试controller

`@Tag`注解用于指定相关测试controller的API

StaffController

package 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 List<Staff> list() { List<Staff> list = staffService.getBaseMapper().selectList(null); log.info("结果值打印--------------------"); list.forEach(System.out::println); return list; }}

YUserController

package 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")@RestControllerpublic 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 List<YUser> queryYUserName(String name){ List<YUser> list = yUserService.getBaseMapper().selectList(new QueryWrapper<YUser>().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

验证swagger

http://localhost:8088/swagger-ui/index.html

浏览器输入这个地址，显示这个页面说明swagger正常。

yml中添加配置

springdoc: api-docs: #是否开启文档功能，默认为true，可不配置 enabled: true swagger-ui: # 访问ip:host/api，可直接访问Swagger springdoc path: /api

配置OpenApiConfig 

package 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)@Configurationpublic 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("517306474@qq.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"; Set<Class<?>> 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 Set<Class<?>> getControllerClasses(String packagePath) { Reflections reflections = reflectionsConf(packagePath); return reflections.getTypesAnnotatedWith(RestController.class); } // 获取单独的controller类 private Class<?> getControllerClass(String packagePath, String controllerName) { Reflections reflections = reflectionsConf(packagePath); Set<Class<?>> controllerClasses = reflections.getTypesAnnotatedWith(RestController.class); for (Class<?> controllerClass : controllerClasses) { if (controllerClass.getSimpleName().equals(controllerName)) { return controllerClass; } } return null; }}

验证配置swagger

http://localhost:8088/api

重启应用，输入此地址，展示以下页面显示配置成功！

验证接口

无参

try一下

执行结果

有参

执行结果

现在看起来是没有问题的，配置，展示，执行结果都是正常，但是这个页面看着削为有点简陋

优化下界面openapi

添加jar包

<!--美化swagger--> <dependency> <groupId>com.github.xiaoymin</groupId> <artifactId>knife4j-springdoc-ui</artifactId> <version>3.0.3</version> </dependency>

  http://localhost:8088/doc.html

重启应用，输入地址，展示以下界面就可以了。

 验证结果

OK执行成功，到此就算是完成了