我要评论描述---痛点
我们项目中很多时候都会用到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>修改时间 2025年4月15日13:20:24 begin
springboot3.2.5版本配置
<dependency>
<groupid>org.reflections</groupid>
<artifactid>reflections</artifactid>
<version>${reflections.version}</version>
<exclusions>
<exclusion>
<artifactid>javassist</artifactid>
<groupid>org.javassist</groupid>
</exclusion>
</exclusions>
</dependency>
<dependency>
<groupid>org.springdoc</groupid>
<artifactid>springdoc-openapi-starter-webmvc-ui</artifactid>
<version>2.3.0</version>
</dependency>
<dependency>
<groupid>com.github.xiaoymin</groupid>
<artifactid>knife4j-openapi3-spring-boot-starter</artifactid>
<version>4.4.0</version>
<exclusions>
<exclusion>
<groupid>org.webjars</groupid>
<artifactid>swagger-ui</artifactid>
</exclusion>
</exclusions>
</dependency>
<!--添加knife4j依赖-->
<dependency>
<groupid>com.github.xiaoymin</groupid>
<artifactid>knife4j-openapi3-jakarta-spring-boot-starter</artifactid>
<version>4.5.0</version>
</dependency>不需要yml中添加配置，添加一个properties即可 knife4j.enable=true knife4j.base-package=cn.axa.provider knife4j.exclude-path=/error knife4j.setting.path=/provider/doc.html knife4j.setting.title=api?? knife4j.setting.description=api?? knife4j.setting.version=1.0.0 knife4j.setting.license.name=apache 2.0
修改时间 2025年4月15日13:20:36 end
新增测试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")
@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://www.jb51.net/program/343957cn3.htm
验证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)
@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("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
重启应用，输入此地址，展示以下页面显示配置成功！
验证接口
无参
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执行成功，到此就算是完成了
到此这篇关于springboot集成springdoc-openapi(模拟前端请求)的文章就介绍到这了,更多相关springboot集成springdoc-openapi内容请搜索代码网以前的文章或继续浏览下面的相关文章希望大家以后多多支持代码网！
发表评论