springboot集成springdoc-openapi的案例讲解(模拟前端请求)_开发_开发者

1. 成熟度和维护性：
2. 依赖和配置：
3. 注解和使用方式：
4. 特性和扩展性：
应用目录结构
pom文件
springboot3.2.5版本配置
新增测试controller
StaffController
YUserController
启动测试看下
验证swagger
yml中添加配置
配置OpenApiConfig
验证配置swagger
验证接口
无参
有参
优化下界面openapi
添加jar包
验证结果

描述---痛点

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

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

例如

Application run failed

org.sprijsngframework.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可能更适合你。

应用目录结构

springboot集成springdoc-openapi的案例讲解(模拟前端请求)

pom文件

我用的springboot是2.7.10还是比较新的。

只需要引入springdoc-openapi-ui这一个即可

<parent>
        <groupId&g编程客栈t;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

springboot集成springdoc-openapi的案例讲解(模拟前端请求)

验证swagger

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

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

springboot集成springdoc-openapi的案例讲解(模拟前端请求)

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 termsOfSeCpnbCDervice = "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-http://www.devze.com" + 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

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

springboot集成springdoc-openapi的案例讲解(模拟前端请求)

验证接口

无参

try一下

springboot集成springdoc-openapi的案例讲解(模拟前端请求)

执行结果

springboot集成springdoc-openapi的案例讲解(模拟前端请求)

有参

执行结果

springboot集成springdoc-openapi的案例讲解(模拟前端请求)

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

优化下界面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

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

springboot集成springdoc-openapi的案例讲解(模拟前端请求)

验证结果

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

springboot集成springdoc-openapi的案例讲解(模拟前端请求)

到此这篇关于springboot集成springdoc-openapi(模拟前端请求)的文章就介绍到这了,更多相关springboot集成springdoc-openapi内容请搜索编程客栈(www.devze.com)以前的文章或继续浏览下面的相关文章希望大家以后多多支持编程客栈(www.devze.com)！

springboot集成springdoc-openapi的案例讲解(模拟前端请求)

目录

描述---痛点

Springfox对比springdoc-openapi

1. 成熟度和维护性：

2. 依赖和配置：

3. 注解和使用方式：

4. 特性和扩展性：

应用目录结构

pom文件

springboot3.2.5版本配置

新增测试controller

StaffController

YUserController

启动测试看下

验证swagger

yml中添加配置

配置OpenApiConfig

验证配置swagger

验证接口

无参

有参

优化下界面openapi

添加jar包

验证结果

精彩评论

关注公众号

热门标签

图文推荐

springboot集成springdoc-openapi的案例讲解(模拟前端请求)

目录

描述---痛点

Springfox对比springdoc-openapi

1. 成熟度和维护性：

2. 依赖和配置：

3. 注解和使用方式：

4. 特性和扩展性：

应用目录结构

pom文件

springboot3.2.5版本配置

新增测试controller

StaffController

YUserController

启动测试看下

验证swagger

yml中添加配置

配置OpenApiConfig

验证配置swagger

验证接口

无参

有参

优化下界面openapi

添加jar包

验证结果

更多 开发 相关资讯：

精彩评论

关注公众号

热门标签

图文推荐

更多开发相关资讯：