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执行成功，到此就算是完成了

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

描述---痛点

Springfox对比springdoc-openapi

1. 成熟度和维护性：

2. 依赖和配置：

3. 注解和使用方式：

4. 特性和扩展性：

应用目录结构

pom文件

新增测试controller

StaffController

YUserController

启动测试看下

验证swagger

yml中添加配置

配置OpenApiConfig

验证配置swagger

验证接口

无参

有参

优化下界面openapi

添加jar包

验证结果

热门文章

最新文章

相关课程

相关电子书

相关实验场景

热门

活动广场

任务中心

开发者评测

高校计划

乘风者计划

训练营

阿里云MVP

话题

直播

下载

镜像站

技术资料

插件

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

描述---痛点

Springfox对比springdoc-openapi

1. 成熟度和维护性：

2. 依赖和配置：

3. 注解和使用方式：

4. 特性和扩展性：

应用目录结构

pom文件

新增测试controller

StaffController

YUserController

启动测试看下

验证swagger

yml中添加配置

配置OpenApiConfig

验证配置swagger

验证接口

无参

有参

优化下界面openapi

添加jar包

验证结果

热门文章

最新文章

相关课程

相关电子书

相关实验场景