springboot集成springdoc-openapi(模拟前端请求)

简介: springboot集成springdoc-openapi(模拟前端请求)

描述---痛点

我们项目中很多时候都会用到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")
@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;
    }
}
启动测试看下

启动完成,如果不知道如何搭建新项目的,可以借鉴看下这篇文章,从零到一新建项目

验证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

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>


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

验证结果

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


相关文章
|
3天前
|
Java 关系型数据库 MySQL
如何实现Springboot+camunda+mysql的集成
【7月更文挑战第2天】集成Spring Boot、Camunda和MySQL的简要步骤: 1. 初始化Spring Boot项目,添加Camunda和MySQL驱动依赖。 2. 配置`application.properties`,包括数据库URL、用户名和密码。 3. 设置Camunda引擎属性,指定数据源。 4. 引入流程定义文件(如`.bpmn`)。 5. 创建服务处理流程操作,创建控制器接收请求。 6. Camunda自动在数据库创建表结构。 7. 启动应用,测试流程启动,如通过服务和控制器开始流程实例。 示例代码包括服务类启动流程实例及控制器接口。实际集成需按业务需求调整。
|
15天前
|
消息中间件 Java 测试技术
【RocketMQ系列八】SpringBoot集成RocketMQ-实现普通消息和事务消息
【RocketMQ系列八】SpringBoot集成RocketMQ-实现普通消息和事务消息
27 1
|
18天前
|
前端开发 Java 微服务
Spring Boot与微前端架构的集成开发
Spring Boot与微前端架构的集成开发
|
21天前
|
消息中间件 Java Kafka
springboot集成kafka
springboot集成kafka
20 2
|
9天前
|
消息中间件 Java Kafka
Spring Boot与Apache Kafka Streams的集成
Spring Boot与Apache Kafka Streams的集成
|
16天前
|
JSON 前端开发 JavaScript
【amis低代码前端框架】vue2集成百度低代码前端框架amis
【amis低代码前端框架】vue2集成百度低代码前端框架amis
23 0
|
17天前
|
消息中间件 Java Kafka
Spring Boot与Apache Kafka集成的深度指南
Spring Boot与Apache Kafka集成的深度指南
|
17天前
|
消息中间件 Java Kafka
Spring Boot与Kafka的集成应用
Spring Boot与Kafka的集成应用
|
20天前
|
Java API Spring
Spring Boot中使用Feign进行HTTP请求
Spring Boot中使用Feign进行HTTP请求
|
21天前
|
消息中间件 Java Kafka
Spring Boot与Kafka的集成应用
Spring Boot与Kafka的集成应用