目录
描述---痛点
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 ***.yun.greedy.modules.staff.controller;
import ***.yun.greedy.modules.staff.entity.Staff;
import ***.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 ***.yun.greedy.modules.yuser.controller;
import ***.baomidou.mybatisplus.core.conditions.query.QueryWrapper;
import ***.yun.greedy.modules.yuser.entity.YUser;
import ***.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 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.***/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 ***.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.***/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.***")//Your API Contact Email
.url("https://blog.csdn.***/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 = "***.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>***.github.xiaoymin</groupId>
<artifactId>knife4j-springdoc-ui</artifactId>
<version>3.0.3</version>
</dependency>http://localhost:8088/doc.html
重启应用，输入地址，展示以下界面就可以了。
验证结果
OK执行成功，到此就算是完成了
