集成SpringDoc，代替springfox

pom.xml

@@ -23,7 +23,6 @@
         <maven-jar-plugin.version>3.1.1</maven-jar-plugin.version>
         <HikariCP.version>5.0.1</HikariCP.version>
         <bitwalker.version>1.21</bitwalker.version>
-        <swagger.version>3.0.0</swagger.version>
         <kaptcha.version>2.3.3</kaptcha.version>
         <pagehelper.boot.version>1.4.6</pagehelper.boot.version>
         <pagehelper.version>5.3.3</pagehelper.version>
@@ -37,6 +36,11 @@
         <servlet-api.version>6.0.0</servlet-api.version>
         <guava.version>32.1.1-jre</guava.version>
         <flatten-maven-plugin.version>1.5.0</flatten-maven-plugin.version>
+        <springdoc.version>2.1.0</springdoc.version>
+        <springdoc-openapi-starter-common.version>2.1.0</springdoc-openapi-starter-common.version>
+        <therapi-runtime-javadoc.version>0.15.0</therapi-runtime-javadoc.version>
+
+        <maven-compiler-plugin.verison>3.11.0</maven-compiler-plugin.verison>
     </properties>
 	
     <!-- 依赖声明 -->
@@ -111,19 +115,6 @@
                 <version>${oshi.version}</version>
             </dependency>
 
-            <!-- Swagger3依赖 -->
-            <dependency>
-                <groupId>io.springfox</groupId>
-                <artifactId>springfox-boot-starter</artifactId>
-                <version>${swagger.version}</version>
-                <exclusions>
-                    <exclusion>
-                        <groupId>io.swagger</groupId>
-                        <artifactId>swagger-models</artifactId>
-                    </exclusion>
-                </exclusions>
-            </dependency>
-
             <!-- io常用工具类 -->
             <dependency>
                 <groupId>commons-io</groupId>
@@ -173,12 +164,39 @@
                 <version>${kaptcha.version}</version>
             </dependency>
 
+            <!-- guava -->
             <dependency>
                 <groupId>com.google.guava</groupId>
                 <artifactId>guava</artifactId>
                 <version>${guava.version}</version>
             </dependency>
 
+            <!-- springdoc -->
+            <dependency>
+                <groupId>org.springdoc</groupId>
+                <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
+                <version>${springdoc.version}</version>
+            </dependency>
+
+            <dependency>
+                <groupId>org.springdoc</groupId>
+                <artifactId>springdoc-openapi-starter-webmvc-api</artifactId>
+                <version>${springdoc.version}</version>
+            </dependency>
+
+            <!-- springdocV2包含对spring secuitry的支持 -->
+            <dependency>
+                <groupId>org.springdoc</groupId>
+                <artifactId>springdoc-openapi-starter-common</artifactId>
+                <version>${springdoc-openapi-starter-common.version}</version>
+            </dependency>
+
+            <dependency>
+                <groupId>com.github.therapi</groupId>
+                <artifactId>therapi-runtime-javadoc</artifactId>
+                <version>${therapi-runtime-javadoc.version}</version>
+            </dependency>
+
             <!-- 定时任务-->
             <dependency>
                 <groupId>com.ruoyi</groupId>
@@ -214,6 +232,13 @@
                 <version>${revision}</version>
             </dependency>
 
+            <!-- springdoc模块 -->
+            <dependency>
+                <groupId>com.ruoyi</groupId>
+                <artifactId>ruoyi-common-springdoc</artifactId>
+                <version>${revision}</version>
+            </dependency>
+
             <!-- demo模块 -->
             <dependency>
                 <groupId>com.ruoyi</groupId>
@@ -237,11 +262,18 @@
             <plugin>
                 <groupId>org.apache.maven.plugins</groupId>
                 <artifactId>maven-compiler-plugin</artifactId>
-                <version>3.1</version>
+                <version>${maven-compiler-plugin.verison}</version>
                 <configuration>
                     <source>${java.version}</source>
                     <target>${java.version}</target>
                     <encoding>${project.build.sourceEncoding}</encoding>
+                    <annotationProcessorPaths>
+                        <path>
+                            <groupId>com.github.therapi</groupId>
+                            <artifactId>therapi-runtime-javadoc-scribe</artifactId>
+                            <version>${therapi-runtime-javadoc.version}</version>
+                        </path>
+                    </annotationProcessorPaths>
                 </configuration>
             </plugin>
 

ruoyi-admin/pom.xml

@@ -24,19 +24,6 @@
             <optional>true</optional> <!-- 表示依赖不会传递 -->
         </dependency>
 
-        <!-- swagger3-->
-        <dependency>
-            <groupId>io.springfox</groupId>
-            <artifactId>springfox-boot-starter</artifactId>
-        </dependency>
-
-        <!-- 防止进入swagger页面报类型转换错误，排除3.0.0中的引用，手动增加1.6.2版本 -->
-        <dependency>
-            <groupId>io.swagger</groupId>
-            <artifactId>swagger-models</artifactId>
-            <version>1.6.2</version>
-        </dependency>
-
          <!-- Mysql驱动包 -->
         <dependency>
             <groupId>mysql</groupId>
@@ -67,6 +54,13 @@
             <artifactId>ruoyi-generator</artifactId>
         </dependency>
 
+        <!-- springdoc模块 -->
+        <dependency>
+            <groupId>com.ruoyi</groupId>
+            <artifactId>ruoyi-common-springdoc</artifactId>
+            <version>${revision}</version>
+        </dependency>
+
         <!--  demo模块  -->
         <dependency>
             <groupId>com.ruoyi</groupId>

ruoyi-admin/src/main/java/com/ruoyi/web/controller/tool/TestController.java

@@ -1,183 +0,0 @@
-package com.ruoyi.web.controller.tool;
-
-import java.util.ArrayList;
-import java.util.LinkedHashMap;
-import java.util.List;
-import java.util.Map;
-import org.springframework.web.bind.annotation.DeleteMapping;
-import org.springframework.web.bind.annotation.GetMapping;
-import org.springframework.web.bind.annotation.PathVariable;
-import org.springframework.web.bind.annotation.PostMapping;
-import org.springframework.web.bind.annotation.PutMapping;
-import org.springframework.web.bind.annotation.RequestBody;
-import org.springframework.web.bind.annotation.RequestMapping;
-import org.springframework.web.bind.annotation.RestController;
-import com.ruoyi.common.core.core.controller.BaseController;
-import com.ruoyi.common.core.core.domain.R;
-import com.ruoyi.common.core.utils.StringUtils;
-import io.swagger.annotations.Api;
-import io.swagger.annotations.ApiImplicitParam;
-import io.swagger.annotations.ApiImplicitParams;
-import io.swagger.annotations.ApiModel;
-import io.swagger.annotations.ApiModelProperty;
-import io.swagger.annotations.ApiOperation;
-
-/**
- * swagger 用户测试方法
- * 
- * @author ruoyi
- */
-@Api("用户信息管理")
-@RestController
-@RequestMapping("/test/user")
-public class TestController extends BaseController
-{
-    private final static Map<Integer, UserEntity> users = new LinkedHashMap<Integer, UserEntity>();
-    {
-        users.put(1, new UserEntity(1, "admin", "admin123", "15888888888"));
-        users.put(2, new UserEntity(2, "ry", "admin123", "15666666666"));
-    }
-
-    @ApiOperation("获取用户列表")
-    @GetMapping("/list")
-    public R<List<UserEntity>> userList()
-    {
-        List<UserEntity> userList = new ArrayList<UserEntity>(users.values());
-        return R.ok(userList);
-    }
-
-    @ApiOperation("获取用户详细")
-    @ApiImplicitParam(name = "userId", value = "用户ID", required = true, dataType = "int", paramType = "path", dataTypeClass = Integer.class)
-    @GetMapping("/{userId}")
-    public R<UserEntity> getUser(@PathVariable Integer userId)
-    {
-        if (!users.isEmpty() && users.containsKey(userId))
-        {
-            return R.ok(users.get(userId));
-        }
-        else
-        {
-            return R.fail("用户不存在");
-        }
-    }
-
-    @ApiOperation("新增用户")
-    @ApiImplicitParams({
-        @ApiImplicitParam(name = "userId", value = "用户id", dataType = "Integer", dataTypeClass = Integer.class),
-        @ApiImplicitParam(name = "username", value = "用户名称", dataType = "String", dataTypeClass = String.class),
-        @ApiImplicitParam(name = "password", value = "用户密码", dataType = "String", dataTypeClass = String.class),
-        @ApiImplicitParam(name = "mobile", value = "用户手机", dataType = "String", dataTypeClass = String.class)
-    })
-    @PostMapping("/save")
-    public R<String> save(UserEntity user)
-    {
-        if (StringUtils.isNull(user) || StringUtils.isNull(user.getUserId()))
-        {
-            return R.fail("用户ID不能为空");
-        }
-        users.put(user.getUserId(), user);
-        return R.ok();
-    }
-
-    @ApiOperation("更新用户")
-    @PutMapping("/update")
-    public R<String> update(@RequestBody UserEntity user)
-    {
-        if (StringUtils.isNull(user) || StringUtils.isNull(user.getUserId()))
-        {
-            return R.fail("用户ID不能为空");
-        }
-        if (users.isEmpty() || !users.containsKey(user.getUserId()))
-        {
-            return R.fail("用户不存在");
-        }
-        users.remove(user.getUserId());
-        users.put(user.getUserId(), user);
-        return R.ok();
-    }
-
-    @ApiOperation("删除用户信息")
-    @ApiImplicitParam(name = "userId", value = "用户ID", required = true, dataType = "int", paramType = "path", dataTypeClass = Integer.class)
-    @DeleteMapping("/{userId}")
-    public R<String> delete(@PathVariable Integer userId)
-    {
-        if (!users.isEmpty() && users.containsKey(userId))
-        {
-            users.remove(userId);
-            return R.ok();
-        }
-        else
-        {
-            return R.fail("用户不存在");
-        }
-    }
-}
-
-@ApiModel(value = "UserEntity", description = "用户实体")
-class UserEntity
-{
-    @ApiModelProperty("用户ID")
-    private Integer userId;
-
-    @ApiModelProperty("用户名称")
-    private String username;
-
-    @ApiModelProperty("用户密码")
-    private String password;
-
-    @ApiModelProperty("用户手机")
-    private String mobile;
-
-    public UserEntity()
-    {
-
-    }
-
-    public UserEntity(Integer userId, String username, String password, String mobile)
-    {
-        this.userId = userId;
-        this.username = username;
-        this.password = password;
-        this.mobile = mobile;
-    }
-
-    public Integer getUserId()
-    {
-        return userId;
-    }
-
-    public void setUserId(Integer userId)
-    {
-        this.userId = userId;
-    }
-
-    public String getUsername()
-    {
-        return username;
-    }
-
-    public void setUsername(String username)
-    {
-        this.username = username;
-    }
-
-    public String getPassword()
-    {
-        return password;
-    }
-
-    public void setPassword(String password)
-    {
-        this.password = password;
-    }
-
-    public String getMobile()
-    {
-        return mobile;
-    }
-
-    public void setMobile(String mobile)
-    {
-        this.mobile = mobile;
-    }
-}

ruoyi-admin/src/main/java/com/ruoyi/web/core/config/SwaggerConfig.java

@@ -1,125 +0,0 @@
-package com.ruoyi.web.core.config;
-
-import java.util.ArrayList;
-import java.util.List;
-import org.springframework.beans.factory.annotation.Autowired;
-import org.springframework.beans.factory.annotation.Value;
-import org.springframework.context.annotation.Bean;
-import org.springframework.context.annotation.Configuration;
-import com.ruoyi.common.core.config.RuoYiConfig;
-import io.swagger.annotations.ApiOperation;
-import io.swagger.models.auth.In;
-import springfox.documentation.builders.ApiInfoBuilder;
-import springfox.documentation.builders.PathSelectors;
-import springfox.documentation.builders.RequestHandlerSelectors;
-import springfox.documentation.service.ApiInfo;
-import springfox.documentation.service.ApiKey;
-import springfox.documentation.service.AuthorizationScope;
-import springfox.documentation.service.Contact;
-import springfox.documentation.service.SecurityReference;
-import springfox.documentation.service.SecurityScheme;
-import springfox.documentation.spi.DocumentationType;
-import springfox.documentation.spi.service.contexts.SecurityContext;
-import springfox.documentation.spring.web.plugins.Docket;
-
-/**
- * Swagger2的接口配置
- * 
- * @author ruoyi
- */
-@Configuration
-public class SwaggerConfig
-{
-    /** 系统基础配置 */
-    @Autowired
-    private RuoYiConfig ruoyiConfig;
-
-    /** 是否开启swagger */
-    @Value("${swagger.enabled}")
-    private boolean enabled;
-
-    /** 设置请求的统一前缀 */
-    @Value("${swagger.pathMapping}")
-    private String pathMapping;
-
-    /**
-     * 创建API
-     */
-    @Bean
-    public Docket createRestApi()
-    {
-        return new Docket(DocumentationType.OAS_30)
-                // 是否启用Swagger
-                .enable(enabled)
-                // 用来创建该API的基本信息，展示在文档的页面中（自定义展示的信息）
-                .apiInfo(apiInfo())
-                // 设置哪些接口暴露给Swagger展示
-                .select()
-                // 扫描所有有注解的api，用这种方式更灵活
-                .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
-                // 扫描指定包中的swagger注解
-                // .apis(RequestHandlerSelectors.basePackage("com.ruoyi.project.tool.swagger"))
-                // 扫描所有 .apis(RequestHandlerSelectors.any())
-                .paths(PathSelectors.any())
-                .build()
-                /* 设置安全模式，swagger可以设置访问token */
-                .securitySchemes(securitySchemes())
-                .securityContexts(securityContexts())
-                .pathMapping(pathMapping);
-    }
-
-    /**
-     * 安全模式，这里指定token通过Authorization头请求头传递
-     */
-    private List<SecurityScheme> securitySchemes()
-    {
-        List<SecurityScheme> apiKeyList = new ArrayList<>();
-        apiKeyList.add(new ApiKey("Authorization", "Authorization", In.HEADER.toValue()));
-        return apiKeyList;
-    }
-
-    /**
-     * 安全上下文
-     */
-    private List<SecurityContext> securityContexts()
-    {
-        List<SecurityContext> securityContexts = new ArrayList<>();
-        securityContexts.add(
-                SecurityContext.builder()
-                        .securityReferences(defaultAuth())
-                        .operationSelector(o -> o.requestMappingPattern().matches("/.*"))
-                        .build());
-        return securityContexts;
-    }
-
-    /**
-     * 默认的安全上引用
-     */
-    private List<SecurityReference> defaultAuth()
-    {
-        AuthorizationScope authorizationScope = new AuthorizationScope("global", "accessEverything");
-        AuthorizationScope[] authorizationScopes = new AuthorizationScope[1];
-        authorizationScopes[0] = authorizationScope;
-        List<SecurityReference> securityReferences = new ArrayList<>();
-        securityReferences.add(new SecurityReference("Authorization", authorizationScopes));
-        return securityReferences;
-    }
-
-    /**
-     * 添加摘要信息
-     */
-    private ApiInfo apiInfo()
-    {
-        // 用ApiInfoBuilder进行定制
-        return new ApiInfoBuilder()
-                // 设置标题
-                .title("标题：若依管理系统_接口文档")
-                // 描述
-                .description("描述：用于管理集团旗下公司的人员信息,具体包括XXX,XXX模块...")
-                // 作者信息
-                .contact(new Contact(ruoyiConfig.getName(), null, null))
-                // 版本
-                .version("版本号:" + ruoyiConfig.getVersion())
-                .build();
-    }
-}

ruoyi-admin/src/main/resources/application-dev.yml

@@ -25,7 +25,12 @@ mybatis-flex:
         max-lifetime: 1800000
         # 数据库连接超时时间,默认30秒
         connection-timeout: 30000
+        # 校验超时时间
+        validationTimeout: 5000
+        # 多久检查一次连接的活性
+        keepaliveTime: 30000
         # 连接测试query
         connection-test-query: SELECT 1
 
 
+

ruoyi-admin/src/main/resources/application.yml

@@ -125,12 +125,23 @@ pagehelper:
   supportMethodsArguments: true
   params: count=countSql
 
-# Swagger配置
+# SpringDoc配置
-swagger:
+springdoc:
-  # 是否开启swagger
+  packages-to-scan: ##需要扫描的包,可以配置多个
-  enabled: true
+    - com.ruoyi.demo.*
-  # 请求前缀
+  paths-to-exclude:  ##配置不包含在swagger文档中的api
-  pathMapping: /dev-api
+    - /api/test/**
+    - /api/mockito/data
+  swagger-ui:
+    enabled: true  #开启/禁止swagger,prod可以设置为false
+    path: /swagger-ui.html  #swagger页面
+    csrf:
+      enabled: true # 启用CSRF支持
+  api-docs:
+    enabled: true #开启/禁止api-docs, prod可以设置为false
+    path: /api-docs #api的json文档
+  use-management-port: false
+  enable-spring-security: true
 
 # 防止XSS攻击
 xss:

ruoyi-common/ruoyi-common-springdoc/pom.xml

@@ -16,7 +16,27 @@
     </description>
 
     <dependencies>
+        <!-- springdoc -->
+        <dependency>
+            <groupId>org.springdoc</groupId>
+            <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
+        </dependency>
 
+        <dependency>
+            <groupId>org.springdoc</groupId>
+            <artifactId>springdoc-openapi-starter-webmvc-api</artifactId>
+        </dependency>
+
+        <dependency>
+            <groupId>org.springdoc</groupId>
+            <artifactId>springdoc-openapi-starter-common</artifactId>
+        </dependency>
+
+        <!-- Runtime library -->
+        <dependency>
+            <groupId>com.github.therapi</groupId>
+            <artifactId>therapi-runtime-javadoc</artifactId>
+        </dependency>
         
     </dependencies>
 

ruoyi-common/ruoyi-common-springdoc/src/main/java/com/ruoyi/common/springdoc/SpringDocConfig.java

@@ -0,0 +1,45 @@
+package com.ruoyi.common.springdoc;
+
+import io.swagger.v3.oas.models.Components;
+import io.swagger.v3.oas.models.ExternalDocumentation;
+import io.swagger.v3.oas.models.OpenAPI;
+import io.swagger.v3.oas.models.info.Info;
+import io.swagger.v3.oas.models.info.License;
+import io.swagger.v3.oas.models.security.SecurityRequirement;
+import io.swagger.v3.oas.models.security.SecurityScheme;
+import org.springframework.context.annotation.Bean;
+import org.springframework.context.annotation.Configuration;
+
+import java.util.ArrayList;
+import java.util.List;
+
+/**
+ * SpringDoc API文档相关配置
+ * @author  数据小王子 on 2023/07/24.
+ */
+@Configuration
+public class SpringDocConfig {
+    @Bean
+    public OpenAPI openAPI() {
+        SecurityRequirement securityRequirement = new SecurityRequirement().addList("Authorization"); // 名字和创建的SecuritySchemes一致
+        List<SecurityRequirement> list = new ArrayList<>();
+        list.add(securityRequirement);
+        return new OpenAPI()
+                .components(new Components().addSecuritySchemes("Authorization", // key值
+                        new SecurityScheme()
+                                .type(SecurityScheme.Type.APIKEY) //请求认证类型
+                                .scheme("bearer").bearerFormat("JWT")
+                                .name("Authorization") //API key参数名
+                                .description("token令牌") //API key描述
+                                .in(SecurityScheme.In.HEADER))) //设置API key的存放位置
+                .security(list)
+                .info(new Info().title("Ruoyi-Flex API Doc")
+                        .description("Ruoyi-Flex SrpingDoc demo")
+                        .version("v4.1.2")
+                        .license(new License().name("MIT").url("https://opensource.org/licenses/MIT")))
+                .externalDocs(new ExternalDocumentation()
+                        .description("Ruoyi-Flex Wiki Documentation")
+                        .url("https://gitee.com/dataprince/ruoyi-flex"));
+    }
+
+}

ruoyi-framework/src/main/java/com/ruoyi/framework/config/SecurityConfig.java

@@ -111,7 +111,8 @@ public class SecurityConfig
                         .requestMatchers("/login", "/register", "/captchaImage","/captcha/get", "/captcha/check").permitAll()
                         // 静态资源，可匿名访问
                         .requestMatchers(HttpMethod.GET, "/*.html", "/*/*.html", "/*/*.css", "/*/*.js", "/profile/**").permitAll()
-                        .requestMatchers("/swagger-ui.html", "/swagger-resources/**", "/webjars/**", "/*/api-docs").permitAll()
+                        .requestMatchers("/swagger-resources/**", "/webjars/**", "/*/api-docs").permitAll()
+                        .requestMatchers("/swagger-ui.html","/swagger-ui/**", "/v3/api-docs/**").permitAll()
                         //设置 @PermitAll 无需认证
                         .requestMatchers(HttpMethod.GET, permitAllUrls.get(HttpMethod.GET).toArray(new String[0])).permitAll()
                         .requestMatchers(HttpMethod.POST, permitAllUrls.get(HttpMethod.POST).toArray(new String[0])).permitAll()

ruoyi-ui/src/views/tool/swagger/index.vue

@@ -8,7 +8,7 @@ export default {
   components: { iFrame },
   data() {
     return {
-      url: process.env.VUE_APP_BASE_API + "/swagger-ui/index.html"
+      url: process.env.VUE_APP_BASE_API + "/swagger-ui.html"
     };
   },
 };