feat():swagger3

2025-08-14 09:41:07 +08:00
parent 37d9a52d03
commit ac60645b59
47 changed files with 770 additions and 799 deletions
--- a/ruoyi-admin/src/main/java/com/ruoyi/web/config/SwaggerConfig.java
+++ b/ruoyi-admin/src/main/java/com/ruoyi/web/config/SwaggerConfig.java
@@ -0,0 +1,59 @@
+package com.ruoyi.web.config;
+
+import com.ruoyi.common.config.RuoYiConfig;
+import io.swagger.v3.oas.models.Components;
+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.security.SecurityRequirement;
+import io.swagger.v3.oas.models.security.SecurityScheme;
+import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.context.annotation.Bean;
+import org.springframework.context.annotation.Configuration;
+
+@Configuration
+public class SwaggerConfig
+{
+    /** 系统基础配置 */
+    @Autowired
+    private RuoYiConfig ruoyiConfig;
+
+    /**
+     * 自定义的 OpenAPI 对象
+     */
+    @Bean
+    public OpenAPI customOpenApi()
+    {
+        return new OpenAPI().components(new Components()
+                        // 设置认证的请求头
+                        .addSecuritySchemes("apikey", securityScheme()))
+                .addSecurityItem(new SecurityRequirement().addList("apikey"))
+                .info(getApiInfo());
+    }
+
+    @Bean
+    public SecurityScheme securityScheme()
+    {
+        return new SecurityScheme()
+                .type(SecurityScheme.Type.APIKEY)
+                .name("Authorization")
+                .in(SecurityScheme.In.HEADER)
+                .scheme("Bearer");
+    }
+
+    /**
+     * 添加摘要信息
+     */
+    public Info getApiInfo()
+    {
+        return new Info()
+                // 设置标题
+                .title("标题：若依管理系统_接口文档")
+                // 描述
+                .description("描述：用于管理集团旗下公司的人员信息,具体包括XXX,XXX模块...")
+                // 作者信息
+                .contact(new Contact().name(ruoyiConfig.getName()))
+                // 版本
+                .version("版本号:" + ruoyiConfig.getVersion());
+    }
+}
--- a/ruoyi-admin/src/main/java/com/ruoyi/web/controller/tool/TestController.java
+++ b/ruoyi-admin/src/main/java/com/ruoyi/web/controller/tool/TestController.java
@@ -4,6 +4,13 @@ import java.util.ArrayList;
 import java.util.LinkedHashMap;
 import java.util.List;
 import java.util.Map;
+
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.Parameter;
+import io.swagger.v3.oas.annotations.Parameters;
+import io.swagger.v3.oas.annotations.enums.ParameterIn;
+import io.swagger.v3.oas.annotations.media.Schema;
+import io.swagger.v3.oas.annotations.tags.Tag;
 import org.springframework.web.bind.annotation.DeleteMapping;
 import org.springframework.web.bind.annotation.GetMapping;
 import org.springframework.web.bind.annotation.PathVariable;
@@ -15,19 +22,13 @@ import org.springframework.web.bind.annotation.RestController;
 import com.ruoyi.common.core.controller.BaseController;
 import com.ruoyi.common.core.domain.R;
 import com.ruoyi.common.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("用户信息管理")
+@Tag(name="用户信息管理")
@RestController
@RequestMapping("/test/user")
 public class TestController extends BaseController
@@ -38,7 +39,7 @@ public class TestController extends BaseController
        users.put(2, new UserEntity(2, "ry", "admin123", "15666666666"));
    }

-    @ApiOperation("获取用户列表")
+    @Operation(summary = "获取用户列表")
    @GetMapping("/list")
    public R<List<UserEntity>> userList()
    {
@@ -46,8 +47,14 @@ public class TestController extends BaseController
        return R.ok(userList);
    }

-    @ApiOperation("获取用户详细")
-    @ApiImplicitParam(name = "userId", value = "用户ID", required = true, dataType = "int", paramType = "path", dataTypeClass = Integer.class)
+    @Operation(summary = "获取用户详细")
+    @Parameter(
+            name = "userId",
+            description = "用户ID",
+            required = true,
+            schema = @Schema(type = "integer", format = "int32"), // 替代 dataType
+            in = ParameterIn.PATH // 替代 paramType
+    )
    @GetMapping("/{userId}")
    public R<UserEntity> getUser(@PathVariable Integer userId)
    {
@@ -61,12 +68,28 @@ public class TestController extends BaseController
        }
    }

-    @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)
+    @Operation(summary = "新增用户")
+    @Parameters({
+            @Parameter(
+                    name = "userId",
+                    description = "用户id",
+                    schema = @Schema(implementation = Integer.class)
+            ),
+            @Parameter(
+                    name = "username",
+                    description = "用户名称",
+                    schema = @Schema(implementation = String.class)
+            ),
+            @Parameter(
+                    name = "password",
+                    description = "用户密码",
+                    schema = @Schema(implementation = String.class)
+            ),
+            @Parameter(
+                    name = "mobile",
+                    description = "用户手机",
+                    schema = @Schema(implementation = String.class)
+            )
    })
    @PostMapping("/save")
    public R<String> save(UserEntity user)
@@ -79,7 +102,7 @@ public class TestController extends BaseController
        return R.ok();
    }

-    @ApiOperation("更新用户")
+    @Operation(summary = "更新用户")
    @PutMapping("/update")
    public R<String> update(@RequestBody UserEntity user)
    {
@@ -96,9 +119,14 @@ public class TestController extends BaseController
        return R.ok();
    }

-    @ApiOperation("删除用户信息")
-    @ApiImplicitParam(name = "userId", value = "用户ID", required = true, dataType = "int", paramType = "path", dataTypeClass = Integer.class)
-    @DeleteMapping("/{userId}")
+    @Operation(summary = "删除用户信息")
+    @Parameter(
+            name = "userId",
+            description = "用户ID",
+            required = true,
+            schema = @Schema(type = "integer", format = "int32"), // 替代 dataType
+            in = ParameterIn.PATH // 替代 paramType
+    )@DeleteMapping("/{userId}")
    public R<String> delete(@PathVariable Integer userId)
    {
        if (!users.isEmpty() && users.containsKey(userId))
@@ -113,19 +141,19 @@ public class TestController extends BaseController
    }
 }

-@ApiModel(value = "UserEntity", description = "用户实体")
+@Schema(description = "用户实体")
 class UserEntity
 {
-    @ApiModelProperty("用户ID")
+    @Schema(description = "用户ID")
    private Integer userId;

-    @ApiModelProperty("用户名称")
+    @Schema(description = "用户名称")
    private String username;

-    @ApiModelProperty("用户密码")
+    @Schema(description = "用户密码")
    private String password;

-    @ApiModelProperty("用户手机")
+    @Schema(description = "用户手机")
    private String mobile;

    public UserEntity()
--- a/ruoyi-admin/src/main/resources/application-druid.yml
+++ b/ruoyi-admin/src/main/resources/application-druid.yml
@@ -7,12 +7,12 @@ spring:
        druid:
            # 主库数据源
            master:
-                #ur#l: jdbc:mysql://47.109.139.82:3306/ngcrm?useUnicode=true&characterEncoding=utf8&zeroDateTimeBehavior=convertToNull&useSSL=true&serverTimezone=GMT%2B8
-                #username: ngcrm
-                #password: ngcrm
-                url: jdbc:mysql://127.0.0.1:3306/ngcrm?useUnicode=true&characterEncoding=utf8&zeroDateTimeBehavior=convertToNull&useSSL=true&serverTimezone=GMT%2B8
-                username: root
-                password: root
+                ur#l: jdbc:mysql://47.109.139.82:3306/cgldb?useUnicode=true&characterEncoding=utf8&zeroDateTimeBehavior=convertToNull&useSSL=true&serverTimezone=GMT%2B8
+                username: cgldb
+                password: cgldb@123456
+#                url: jdbc:mysql://127.0.0.1:3306/ngcrm?useUnicode=true&characterEncoding=utf8&zeroDateTimeBehavior=convertToNull&useSSL=true&serverTimezone=GMT%2B8
+#                username: root
+#                password: root
            # 从库数据源
            slave:
                # 从数据源开关/默认关闭
--- a/ruoyi-admin/src/main/resources/application.yml
+++ b/ruoyi-admin/src/main/resources/application.yml
@@ -126,13 +126,6 @@ pagehelper:
  supportMethodsArguments: true
  params: count=countSql

-# Swagger配置
-swagger:
-  # 是否开启swagger
-  enabled: true
-  # 请求前缀
-  pathMapping: /
-
 # 防止XSS攻击
 xss:
  # 过滤开关
@@ -147,13 +140,24 @@ xss:
  #producer:
    #group: test

-# Knife4j配置
+springdoc:
+  api-docs:
+    path: /v3/api-docs
+  swagger-ui:
+    enabled: true
+    path: /swagger-ui.html
+    tags-sorter: alpha
+  group-configs:
+    - group: 'default'
+      display-name: 'default'
+      paths-to-match: '/**'
+      packages-to-scan: com.fizz.business.controller
+
+
 knife4j:
-  #开启增强配置
-  enable: true
-  #开启生产环境屏蔽
-  production: false
-  basic:
-    enable: false
-    username: admin
-    password: 123456
+  enable: true                  # 启用 Knife4j
+  setting:
+    language: zh-CN             # 中文界面
+    enable-swagger-model: true   # 显示模型
+    enable-document-manage: true # 启用文档管理
+  cors: true                    # 允许跨域