feat: 集成OpenAPI 3.0文档并添加中文接口注解

✨ 新增功能:
- 集成SpringDoc OpenAPI 3.0依赖和配置
- 创建OpenApiConfig配置类，设置中文API文档信息
- 为所有Controller类添加@Tag中文标签注解
- 为所有Controller方法添加@Operation中文描述注解

📝 涉及模块:
- 根pom.xml: 添加springdoc依赖版本管理
- coder-common-thin-web: 添加OpenAPI依赖和配置
- coder-common-thin-system: 添加OpenAPI依赖
- application-dev.yml: 配置SpringDoc参数

🎯 改进内容:
- 用户管理: 15个接口方法的中文注解
- 登录认证: 3个接口方法的中文注解
- 验证码管理: 2个接口方法的中文注解
- 菜单管理: 13个接口方法的中文注解
- 角色管理: 11个接口方法的中文注解
- 文件管理: 2个接口方法的中文注解
- 系统文件管理: 7个接口方法的中文注解
- 图库管理: 7个接口方法的中文注解
- 登录日志: 7个接口方法的中文注解

🚀 使用效果:
- 访问 /swagger-ui.html 可查看完整中文API文档
- 同步到Apifox时显示中文接口名称和描述
- API按功能模块分组，便于管理和使用

coder-common-thin-modules/coder-common-thin-system/pom.xml

@@ -40,6 +40,11 @@
         <!--     <artifactId>coder-common-thin-oper-logs</artifactId> -->
         <!--     <version>${revision}</version> -->
         <!-- </dependency> -->
+        <!-- SpringDoc OpenAPI 3.0 -->
+        <dependency>
+            <groupId>org.springdoc</groupId>
+            <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
+        </dependency>
     </dependencies>
 
 </project>

coder-common-thin-modules/coder-common-thin-system/src/main/java/org/leocoder/thin/system/controller/file/FileController.java

@@ -1,6 +1,8 @@
 package org.leocoder.thin.system.controller.file;
 
 import cn.dev33.satoken.annotation.SaIgnore;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.tags.Tag;
 import com.alibaba.excel.util.StringUtils;
 import lombok.RequiredArgsConstructor;
 import lombok.extern.slf4j.Slf4j;
@@ -25,6 +27,7 @@ import java.util.Map;
  * @author Leocoder
  * @description [FileController]
  */
+@Tag(name = "文件管理", description = "文件上传、下载、删除等操作")
 @Slf4j
 @RequestMapping("/coder")
 @RequiredArgsConstructor
@@ -46,6 +49,7 @@ public class FileController {
      * @description [上传单文件-需在WebConfig配置静态资源]
      * @author Leocoder
      */
+    @Operation(summary = "上传文件", description = "上传单个文件到服务器")
     @PostMapping("/file/uploadFile/{fileSize}/{folderName}/{fileParam}")
     public Map<String, Object> uploadSingleFile(@RequestParam("file") MultipartFile file, @PathVariable("fileSize") Integer fileSize, @PathVariable("folderName") String folderName, @PathVariable("fileParam") String fileParam) {
         Map<String, Object> fileMap = UploadUtil.coderSingleFile(file, basePath + "/" + folderName + "/"+ CoderLoginUtil.getLoginName() + "/", fileSize);
@@ -130,6 +134,7 @@ public class FileController {
      * @description [上传单文件-需在WebConfig配置静态资源]
      * @author Leocoder
      */
+    @Operation(summary = "匿名上传文件", description = "匿名上传单个文件到服务器，无需登录认证")
     @SaIgnore
     @PostMapping("/file/uploadAnyFile/{fileSize}/{folderName}/{fileParam}")
     public Map<String, Object> uploadAnyFile(@RequestParam("file") MultipartFile file, @PathVariable("fileSize") Integer fileSize, @PathVariable("folderName") String folderName, @PathVariable("fileParam") String fileParam) {

coder-common-thin-modules/coder-common-thin-system/src/main/java/org/leocoder/thin/system/controller/file/SysFileController.java

@@ -1,6 +1,8 @@
 package org.leocoder.thin.system.controller.file;
 
 import cn.dev33.satoken.annotation.SaCheckPermission;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.tags.Tag;
 import cn.hutool.core.util.ObjectUtil;
 import com.baomidou.mybatisplus.core.conditions.query.LambdaQueryWrapper;
 import com.baomidou.mybatisplus.core.metadata.IPage;
@@ -24,6 +26,7 @@ import java.util.List;
  * @author Leocoder
  * @description [文件资源表-控制层]
  */
+@Tag(name = "系统文件管理", description = "系统文件资源的增删改查操作")
 @Validated
 @RequestMapping("/coder")
 @RequiredArgsConstructor
@@ -36,6 +39,7 @@ public class SysFileController {
      * @description [分页查询]
      * @author Leocoder
      */
+    @Operation(summary = "分页查询文件列表", description = "根据查询条件分页获取系统文件信息")
     @SaCheckPermission("system:file:list")
     @GetMapping("/sysFile/listPage")
     public IPage<SysFile> listPage(SysFileVo vo) {
@@ -57,6 +61,7 @@ public class SysFileController {
      * @description [查询所有]
      * @author Leocoder
      */
+    @Operation(summary = "查询所有文件", description = "获取系统中所有文件信息")
     @SaCheckPermission("system:file:list")
     @GetMapping("/sysFile/list")
     public List<SysFile> list(SysFileVo vo) {
@@ -73,6 +78,7 @@ public class SysFileController {
      * @description [查询一个]
      * @author Leocoder
      */
+    @Operation(summary = "根据ID查询文件", description = "根据文件ID获取文件详细信息")
     @GetMapping("/sysFile/getById/{id}")
     public SysFile getById(@PathVariable Long id) {
         return sysFileService.getById(id);
@@ -82,6 +88,7 @@ public class SysFileController {
      * @description [新增]
      * @author Leocoder
      */
+    @Operation(summary = "新增文件记录", description = "添加新的文件资源记录")
     @SaCheckPermission("system:file:add")
     @PostMapping("/sysFile/add")
     // @OperLog(value = "新增文件资源", operType = OperType.INSERT)
@@ -94,6 +101,7 @@ public class SysFileController {
      * @description [修改]
      * @author Leocoder
      */
+    @Operation(summary = "修改文件信息", description = "更新系统文件的基本信息")
     @SaCheckPermission("system:file:update")
     @PostMapping("/sysFile/update")
     // @OperLog(value = "修改文件资源", operType = OperType.UPDATE)
@@ -106,6 +114,7 @@ public class SysFileController {
      * @description [删除]
      * @author Leocoder
      */
+    @Operation(summary = "删除文件", description = "根据文件ID删除指定文件及其记录")
     @SaCheckPermission("system:file:delete")
     @PostMapping("/sysFile/deleteById/{id}")
     // @OperLog(value = "删除文件资源", operType = OperType.DELETE)
@@ -124,6 +133,7 @@ public class SysFileController {
      * @description [批量删除]
      * @author Leocoder
      */
+    @Operation(summary = "批量删除文件", description = "批量删除多个文件及其记录")
     @SaCheckPermission("system:file:delete")
     @Transactional(rollbackFor = Exception.class)
     @PostMapping("/sysFile/batchDelete")

coder-common-thin-modules/coder-common-thin-system/src/main/java/org/leocoder/thin/system/controller/login/CaptchaController.java

@@ -1,6 +1,8 @@
 package org.leocoder.thin.system.controller.login;
 
 import com.wf.captcha.GifCaptcha;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.tags.Tag;
 import com.wf.captcha.SpecCaptcha;
 import com.wf.captcha.base.Captcha;
 import lombok.RequiredArgsConstructor;
@@ -21,6 +23,7 @@ import java.util.concurrent.TimeUnit;
  * @author Leocoder
  * @description [三种类型验证码]
  */
+@Tag(name = "验证码管理", description = "生成各种类型的验证码")
 @Slf4j
 @RequiredArgsConstructor
 @RestController
@@ -35,6 +38,7 @@ public class CaptchaController {
      *
      * @author Leocoder
      */
+    @Operation(summary = "生成PNG验证码", description = "生成PNG格式的验证码，6分钟过期")
     @GetMapping("/png")
     public Map<String, String> pngCaptcha() {
         // 三个参数分别为宽、高、位数
@@ -59,6 +63,7 @@ public class CaptchaController {
      *
      * @author Leocoder
      */
+    @Operation(summary = "生成GIF验证码", description = "生成GIF动画格式的验证码，6分钟过期")
     @GetMapping("/gif")
     public Map<String, Object> gifCaptcha() {
         // 三个参数分别为宽、高、位数

coder-common-thin-modules/coder-common-thin-system/src/main/java/org/leocoder/thin/system/controller/login/SysLoginController.java

@@ -1,5 +1,7 @@
 package org.leocoder.thin.system.controller.login;
 
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.tags.Tag;
 import lombok.RequiredArgsConstructor;
 import lombok.extern.slf4j.Slf4j;
 import org.leocoder.thin.domain.model.bo.system.SysLoginBo;
@@ -16,6 +18,7 @@ import org.springframework.web.bind.annotation.RestController;
  * @author Leocoder
  * @description [SysLoginController]
  */
+@Tag(name = "登录认证", description = "用户登录、退出、注册等认证相关操作")
 @Slf4j
 @Validated
 @RequiredArgsConstructor
@@ -28,6 +31,7 @@ public class SysLoginController {
      * @description [PC登录]
      * @author Leocoder
      */
+    @Operation(summary = "用户登录", description = "PC端用户登录接口")
     @PostMapping("/auth/login")
     public SysLoginBo login(@Validated @RequestBody SysLoginVo loginVo) {
         return loginService.login(loginVo);
@@ -40,6 +44,7 @@ public class SysLoginController {
      * @description [退出登录]
      * @author Leocoder
      */
+    @Operation(summary = "用户退出", description = "用户退出登录接口")
     @GetMapping("/auth/logout")
     public String logout() {
         loginService.logout();
@@ -50,6 +55,7 @@ public class SysLoginController {
      * @description [PC注册]
      * @author Leocoder
      */
+    @Operation(summary = "用户注册", description = "PC端用户注册接口")
     @PostMapping("/auth/register")
     public void register(@Validated @RequestBody SysRegisterVo registerVo) {
         loginService.register(registerVo);

coder-common-thin-modules/coder-common-thin-system/src/main/java/org/leocoder/thin/system/controller/loginlog/SysLoginLogController.java

@@ -1,6 +1,8 @@
 package org.leocoder.thin.system.controller.loginlog;
 
 import cn.dev33.satoken.annotation.SaCheckPermission;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.tags.Tag;
 import com.baomidou.mybatisplus.core.conditions.query.LambdaQueryWrapper;
 import com.baomidou.mybatisplus.core.metadata.IPage;
 import com.baomidou.mybatisplus.extension.plugins.pagination.Page;
@@ -20,6 +22,7 @@ import java.util.List;
  * @author Leocoder
  * @description [系统访问记录-控制层]
  */
+@Tag(name = "登录日志", description = "系统登录记录的查询和管理")
 @Validated
 @RequestMapping("/coder")
 @RequiredArgsConstructor
@@ -32,6 +35,7 @@ public class SysLoginLogController {
      * @description [分页查询]
      * @author Leocoder
      */
+    @Operation(summary = "分页查询登录日志", description = "根据查询条件分页获取系统登录记录")
     @SaCheckPermission("system:loginlog:list")
     @GetMapping("/sysLoginLog/listPage")
     public IPage<SysLoginLog> listPage(SysLoginLogVo vo) {
@@ -54,6 +58,7 @@ public class SysLoginLogController {
      * @description [查询所有]
      * @author Leocoder
      */
+    @Operation(summary = "查询所有登录日志", description = "获取系统中所有登录记录")
     @SaCheckPermission("system:loginlog:list")
     @GetMapping("/sysLoginLog/list")
     public List<SysLoginLog> list() {
@@ -64,6 +69,7 @@ public class SysLoginLogController {
      * @description [查询一个]
      * @author Leocoder
      */
+    @Operation(summary = "根据ID查询登录日志", description = "根据日志ID获取登录记录详细信息")
     @GetMapping("/sysLoginLog/getById/{id}")
     public SysLoginLog getById(@PathVariable Long id) {
         return sysLoginLogService.getById(id);
@@ -73,6 +79,7 @@ public class SysLoginLogController {
      * @description [新增]
      * @author Leocoder
      */
+    @Operation(summary = "新增登录日志", description = "添加新的登录记录")
     @SaCheckPermission("system:loginlog:add")
     @PostMapping("/sysLoginLog/add")
     public void add(@Validated @RequestBody SysLoginLog sysLoginLog) {
@@ -83,6 +90,7 @@ public class SysLoginLogController {
      * @description [修改]
      * @author Leocoder
      */
+    @Operation(summary = "修改登录日志", description = "更新登录记录信息")
     @SaCheckPermission("system:loginlog:update")
     @PostMapping("/sysLoginLog/update")
     public void update(@Validated @RequestBody SysLoginLog sysLoginLog) {
@@ -93,6 +101,7 @@ public class SysLoginLogController {
      * @description [删除]
      * @author Leocoder
      */
+    @Operation(summary = "删除登录日志", description = "根据日志ID删除指定登录记录")
     @SaCheckPermission("system:loginlog:delete")
     @PostMapping("/sysLoginLog/deleteById/{id}")
     public void delete(@PathVariable("id") Long id) {
@@ -103,6 +112,7 @@ public class SysLoginLogController {
      * @description [批量删除]
      * @author Leocoder
      */
+    @Operation(summary = "批量删除登录日志", description = "批量删除多个登录记录")
     @SaCheckPermission("system:loginlog:delete")
     @PostMapping("/sysLoginLog/batchDelete")
     public void batchDelete(@NotNull(message = "请选择需要删除的数据") @RequestBody List<Long> ids) {

coder-common-thin-modules/coder-common-thin-system/src/main/java/org/leocoder/thin/system/controller/menu/SysMenuController.java

@@ -1,6 +1,8 @@
 package org.leocoder.thin.system.controller.menu;
 
 import cn.dev33.satoken.annotation.SaCheckPermission;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.tags.Tag;
 import cn.hutool.core.collection.CollectionUtil;
 import com.baomidou.mybatisplus.core.conditions.query.LambdaQueryWrapper;
 import com.baomidou.mybatisplus.core.conditions.update.LambdaUpdateWrapper;
@@ -28,6 +30,7 @@ import java.util.stream.Collectors;
  * @author Leocoder
  * @description [菜单权限表-控制层]
  */
+@Tag(name = "菜单管理", description = "系统菜单权限的增删改查操作")
 @Validated
 @RequestMapping("/coder")
 @RequiredArgsConstructor
@@ -40,6 +43,7 @@ public class SysMenuController {
      * @description [分页查询]
      * @author Leocoder
      */
+    @Operation(summary = "分页查询菜单列表", description = "根据查询条件分页获取系统菜单信息")
     @SaCheckPermission("system:menu:list")
     @GetMapping("/sysMenu/listPage")
     public IPage<SysMenu> listPage(SysMenuVo vo) {
@@ -59,6 +63,7 @@ public class SysMenuController {
      * @description [查询菜单]
      * @author Leocoder
      */
+    @Operation(summary = "查询菜单列表", description = "根据条件查询系统菜单信息")
     @SaCheckPermission("system:menu:list")
     @GetMapping("/sysMenu/list")
     public List<SysMenu> list(SysMenuVo vo) {
@@ -75,6 +80,7 @@ public class SysMenuController {
      * @description [查询一个]
      * @author Leocoder
      */
+    @Operation(summary = "根据ID查询菜单", description = "根据菜单ID获取菜单详细信息")
     @GetMapping("/sysMenu/getById/{id}")
     public SysMenu getById(@PathVariable Long id) {
         return sysMenuService.getById(id);
@@ -84,6 +90,7 @@ public class SysMenuController {
      * @description [新增]
      * @author Leocoder
      */
+    @Operation(summary = "新增菜单", description = "添加新的系统菜单")
     @SaCheckPermission("system:menu:add")
     @PostMapping("/sysMenu/add")
     // @OperLog(value = "新增菜单", operType = OperType.INSERT)
@@ -114,6 +121,7 @@ public class SysMenuController {
      * @description [修改]
      * @author Leocoder
      */
+    @Operation(summary = "修改菜单信息", description = "更新系统菜单的基本信息")
     @SaCheckPermission("system:menu:update")
     @PostMapping("/sysMenu/update")
     // @OperLog(value = "修改菜单", operType = OperType.UPDATE)
@@ -140,6 +148,7 @@ public class SysMenuController {
      * @description [删除]
      * @author Leocoder
      */
+    @Operation(summary = "删除菜单", description = "根据菜单ID删除指定菜单")
     @SaCheckPermission("system:menu:delete")
     @PostMapping("/sysMenu/deleteById/{id}")
     // @OperLog(value = "删除菜单", operType = OperType.DELETE)
@@ -158,6 +167,7 @@ public class SysMenuController {
      * @description [批量删除]
      * @author Leocoder
      */
+    @Operation(summary = "批量删除菜单", description = "批量删除多个系统菜单")
     @SaCheckPermission("system:menu:delete")
     @PostMapping("/sysMenu/batchDelete")
     // @OperLog(value = "批量删除菜单", operType = OperType.DELETE)
@@ -170,6 +180,7 @@ public class SysMenuController {
      * @description [修改状态]
      * @author Leocoder
      */
+    @Operation(summary = "修改菜单状态", description = "启用或禁用系统菜单")
     @SaCheckPermission("system:menu:update")
     @PostMapping("/sysMenu/updateStatus/{id}/{menuStatus}")
     // @OperLog(value = "修改菜单状态", operType = OperType.UPDATE)
@@ -183,6 +194,7 @@ public class SysMenuController {
      * @description [是否展开]
      * @author Leocoder
      */
+    @Operation(summary = "修改菜单展开状态", description = "设置菜单是否默认展开")
     @PostMapping("/sysMenu/updateSpread/{id}/{isSpread}")
     // @OperLog(value = "修改菜单展开状态", operType = OperType.UPDATE)
     public void updateSpread(@PathVariable("id") Long id, @PathVariable("isSpread") String isSpread) {
@@ -195,6 +207,7 @@ public class SysMenuController {
      * @description [菜单级联下拉框]
      * @author Leocoder
      */
+    @Operation(summary = "菜单级联下拉框", description = "获取菜单的树形级联选择器数据")
     @GetMapping("/sysMenu/cascaderList")
     public List<CascaderLongBo> cascaderList() {
         return sysMenuService.cascaderList();
@@ -205,6 +218,7 @@ public class SysMenuController {
      * @description [生成当前用户所拥有菜单路由]
      * @author Leocoder
      */
+    @Operation(summary = "生成用户菜单路由", description = "根据当前用户权限生成可访问的菜单路由")
     @GetMapping("/sysMenu/listRouters")
     public List<SysMenuBo> generatorRouters() {
         return sysMenuService.generatorRouters();
@@ -214,6 +228,7 @@ public class SysMenuController {
      * @description [查询所有正常的路由 AND 展开节点（角色分配菜单权限使用）]
      * @author Leocoder
      */
+    @Operation(summary = "查询正常菜单列表", description = "查询所有正常状态的菜单和展开节点，用于角色分配权限")
     @GetMapping("/sysMenu/listMenuNormal")
     public Map<String, Object> listMenuNormal(SysMenuVo sysMenuVo) {
         Map<String, Object> map = new HashMap<>();
@@ -244,6 +259,7 @@ public class SysMenuController {
      * @description [根据用户拥有的角色ID查询权限菜单]
      * @author Leocoder
      */
+    @Operation(summary = "根据角色ID查询菜单", description = "根据角色ID获取该角色拥有的菜单权限ID列表")
     @GetMapping("/sysMenu/listMenuIdsByRoleId/{roleId}")
     public List<Long> listMenuIdsByRoleId(@PathVariable("roleId") Long roleId) {
         return sysMenuService.listMenuIdsByRoleId(roleId);
@@ -253,6 +269,7 @@ public class SysMenuController {
      * @description [保存角色和菜单权限之间的关系]
      * @author Leocoder
      */
+    @Operation(summary = "保存角色菜单权限", description = "保存角色和菜单权限之间的关联关系")
     @SaCheckPermission("system:role:menu")
     @PostMapping("/sysMenu/saveRoleMenu/{roleId}/{menuIds}")
     // @OperLog(value = "保存角色菜单权限", operType = OperType.UPDATE)

coder-common-thin-modules/coder-common-thin-system/src/main/java/org/leocoder/thin/system/controller/picture/SysPictureController.java

@@ -1,6 +1,8 @@
 package org.leocoder.thin.system.controller.picture;
 
 import cn.dev33.satoken.annotation.SaCheckPermission;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.tags.Tag;
 import com.baomidou.mybatisplus.core.conditions.query.LambdaQueryWrapper;
 import com.baomidou.mybatisplus.core.metadata.IPage;
 import com.baomidou.mybatisplus.extension.plugins.pagination.Page;
@@ -22,6 +24,7 @@ import java.util.List;
  * @author Leocoder
  * @description [图库表-控制层]
  */
+@Tag(name = "图库管理", description = "系统图片资源的增删改查操作")
 @Validated
 @RequestMapping("/coder")
 @RequiredArgsConstructor
@@ -34,6 +37,7 @@ public class SysPictureController {
      * @description [分页查询]
      * @author Leocoder
      */
+    @Operation(summary = "分页查询图片列表", description = "根据查询条件分页获取系统图片信息")
     @SaCheckPermission("system:picture:list")
     @GetMapping("/sysPicture/listPage")
     public IPage<SysPicture> listPage(SysPictureVo vo) {
@@ -54,6 +58,7 @@ public class SysPictureController {
      * @description [查询所有]
      * @author Leocoder
      */
+    @Operation(summary = "查询所有图片", description = "获取系统中所有图片信息")
     @SaCheckPermission("system:picture:list")
     @GetMapping("/sysPicture/list")
     public List<SysPicture> list(SysPictureVo vo) {
@@ -69,6 +74,7 @@ public class SysPictureController {
      * @description [查询一个]
      * @author Leocoder
      */
+    @Operation(summary = "根据ID查询图片", description = "根据图片ID获取图片详细信息")
     @GetMapping("/sysPicture/getById/{id}")
     public SysPicture getById(@PathVariable Long id) {
         return sysPictureService.getById(id);
@@ -78,6 +84,7 @@ public class SysPictureController {
      * @description [新增]
      * @author Leocoder
      */
+    @Operation(summary = "新增图片记录", description = "添加新的图片资源记录")
     @SaCheckPermission("system:sysPicture:add")
     @PostMapping("/sysPicture/add")
     // @OperLog(value = "新增图库", operType = OperType.INSERT)
@@ -90,6 +97,7 @@ public class SysPictureController {
      * @description [修改]
      * @author Leocoder
      */
+    @Operation(summary = "修改图片信息", description = "更新系统图片的基本信息")
     @SaCheckPermission("system:sysPicture:update")
     @PostMapping("/sysPicture/update")
     // @OperLog(value = "修改图库", operType = OperType.UPDATE)
@@ -102,6 +110,7 @@ public class SysPictureController {
      * @description [删除]
      * @author Leocoder
      */
+    @Operation(summary = "删除图片", description = "根据图片ID删除指定图片记录")
     @SaCheckPermission("system:sysPicture:delete")
     @PostMapping("/sysPicture/deleteById/{id}")
     // @OperLog(value = "删除图库", operType = OperType.DELETE)
@@ -113,6 +122,7 @@ public class SysPictureController {
      * @description [批量删除]
      * @author Leocoder
      */
+    @Operation(summary = "批量删除图片", description = "批量删除多个图片记录")
     @SaCheckPermission("system:sysPicture:delete")
     @Transactional(rollbackFor = Exception.class)
     @PostMapping("/sysPicture/batchDelete")

coder-common-thin-modules/coder-common-thin-system/src/main/java/org/leocoder/thin/system/controller/role/SysRoleController.java

@@ -4,6 +4,8 @@ import cn.dev33.satoken.annotation.SaCheckPermission;
 import com.baomidou.mybatisplus.core.conditions.query.LambdaQueryWrapper;
 import com.baomidou.mybatisplus.core.conditions.update.UpdateWrapper;
 import com.baomidou.mybatisplus.core.metadata.IPage;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.tags.Tag;
 import lombok.RequiredArgsConstructor;
 import org.apache.commons.lang3.StringUtils;
 import org.leocoder.thin.common.constants.CoderConstants;
@@ -27,6 +29,7 @@ import java.util.Objects;
  * @author Leocoder
  * @description [角色信息表-控制层]
  */
+@Tag(name = "角色管理", description = "系统角色权限的增删改查操作")
 @Validated
 @RequestMapping("/coder")
 @RequiredArgsConstructor
@@ -39,6 +42,7 @@ public class SysRoleController {
      * @description [分页查询]
      * @author Leocoder
      */
+    @Operation(summary = "分页查询角色列表", description = "根据查询条件分页获取系统角色信息")
     @SaCheckPermission("system:role:list")
     @GetMapping("/sysRole/listPage")
     public IPage<SysRole> listPage(SysRoleVo vo) {
@@ -49,6 +53,7 @@ public class SysRoleController {
      * @description [查询所有]
      * @author Leocoder
      */
+    @Operation(summary = "查询所有角色", description = "获取系统中所有角色信息")
     @SaCheckPermission("system:role:list")
     @GetMapping("/sysRole/list")
     public List<SysRole> list() {
@@ -59,6 +64,7 @@ public class SysRoleController {
      * @description [根据主键查询]
      * @author Leocoder
      */
+    @Operation(summary = "根据ID查询角色", description = "根据角色ID获取角色详细信息")
     @GetMapping("/sysRole/getById/{id}")
     public SysRole getById(@PathVariable("id") Long id) {
         return sysRoleService.getById(id);
@@ -68,6 +74,7 @@ public class SysRoleController {
      * @description [新增]
      * @author Leocoder
      */
+    @Operation(summary = "新增角色", description = "添加新的系统角色")
     @SaCheckPermission("system:role:add")
     @PostMapping("/sysRole/add")
     // @OperLog(value = "新增角色", operType = OperType.INSERT)
@@ -82,6 +89,7 @@ public class SysRoleController {
      * @description [获取最新排序]
      * @author Leocoder
      */
+    @Operation(summary = "获取最新排序号", description = "获取当前最大的角色排序号用于新增")
     @GetMapping("/sysRole/getSorted")
     public int getSorted() {
         LambdaQueryWrapper<SysRole> lambdaQueryWrapper = new LambdaQueryWrapper<>();
@@ -97,6 +105,7 @@ public class SysRoleController {
      * @description [修改]
      * @author Leocoder
      */
+    @Operation(summary = "修改角色信息", description = "更新系统角色的基本信息")
     @SaCheckPermission("system:role:update")
     @PostMapping("/sysRole/update")
     // @OperLog(value = "修改角色", operType = OperType.UPDATE)
@@ -111,6 +120,7 @@ public class SysRoleController {
      * @description [删除]
      * @author Leocoder
      */
+    @Operation(summary = "删除角色", description = "根据角色ID删除指定角色")
     @SaCheckPermission("system:role:delete")
     @PostMapping("/sysRole/deleteById/{id}")
     // @OperLog(value = "删除角色", operType = OperType.DELETE)
@@ -123,6 +133,7 @@ public class SysRoleController {
      * @description [批量删除]
      * @author Leocoder
      */
+    @Operation(summary = "批量删除角色", description = "批量删除多个系统角色")
     @SaCheckPermission("system:role:delete")
     @PostMapping("/sysRole/batchDelete")
     // @OperLog(value = "批量删除角色", operType = OperType.DELETE)
@@ -137,6 +148,7 @@ public class SysRoleController {
      * @description [修改状态]
      * @author Leocoder
      */
+    @Operation(summary = "修改角色状态", description = "启用或禁用系统角色")
     @PostMapping("/sysRole/updateStatus/{roleId}/{roleStatus}")
     // @OperLog(value = "修改角色状态", operType = OperType.UPDATE)
     public void update(@PathVariable("roleId") Long roleId, @PathVariable("roleStatus") String roleStatus) {
@@ -149,6 +161,7 @@ public class SysRoleController {
      * @description [查询所有正常角色-穿梭框]
      * @author Leocoder
      */
+    @Operation(summary = "查询正常角色穿梭框", description = "查询所有正常状态的角色，用于穿梭框组件")
     @SaCheckPermission("system:user:role")
     @GetMapping("/sysRole/listNormalRole/{userId}")
     public Map<String, Object> listNormalRole(@PathVariable("userId") Long userId) {
@@ -162,6 +175,7 @@ public class SysRoleController {
      * @description [根据当前用户ID分配角色-穿梭框]
      * @author Leocoder
      */
+    @Operation(summary = "分配用户角色", description = "为指定用户分配角色权限")
     @SaCheckPermission("system:user:role")
     @GetMapping("/sysRole/assignUserRole/{userId}/{roleIds}")
     // @OperLog(value = "分配用户角色", operType = OperType.UPDATE)
@@ -173,6 +187,7 @@ public class SysRoleController {
      * @description [获取当前用户分配得角色下拉框(不需要可以删除注释和vo)]
      * @author Leocoder
      */
+    @Operation(summary = "获取角色下拉框", description = "获取当前用户可分配的角色下拉选项")
     @GetMapping("/sysRole/listRoleElSelect")
     public List<SelectLongBo> listRoleElSelect(BaseVo vo) {
         return sysRoleService.listRoleElSelect(vo);

coder-common-thin-modules/coder-common-thin-system/src/main/java/org/leocoder/thin/system/controller/user/SysLoginUserController.java

@@ -1,6 +1,9 @@
 package org.leocoder.thin.system.controller.user;
 
 import cn.dev33.satoken.annotation.SaCheckPermission;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.Parameter;
+import io.swagger.v3.oas.annotations.tags.Tag;
 import com.baomidou.mybatisplus.core.conditions.query.LambdaQueryWrapper;
 import com.baomidou.mybatisplus.core.conditions.update.LambdaUpdateWrapper;
 import com.baomidou.mybatisplus.core.conditions.update.UpdateWrapper;
@@ -39,6 +42,7 @@ import java.util.Map;
  * @author Leocoder
  * @description [用户信息表-控制层]
  */
+@Tag(name = "用户管理", description = "系统用户信息的增删改查操作")
 @Slf4j
 @Validated
 @RequestMapping("/coder")
@@ -57,6 +61,7 @@ public class SysLoginUserController {
      * @description [分页查询]
      * @author Leocoder
      */
+    @Operation(summary = "分页查询用户列表", description = "根据查询条件分页获取系统用户信息")
     @SaCheckPermission("system:user:list")
     @GetMapping("/sysLoginUser/listPage")
     public IPage<SysLoginUser> listPage(SysLoginUserVo vo) {
@@ -67,6 +72,7 @@ public class SysLoginUserController {
      * @description [查询所有]
      * @author Leocoder
      */
+    @Operation(summary = "查询所有用户", description = "获取系统中所有用户信息")
     @SaCheckPermission("system:user:list")
     @GetMapping("/sysLoginUser/list")
     public List<SysLoginUser> list() {
@@ -77,6 +83,7 @@ public class SysLoginUserController {
      * @description [查询一个]
      * @author Leocoder
      */
+    @Operation(summary = "根据ID查询用户", description = "根据用户ID获取用户详细信息")
     @GetMapping("/sysLoginUser/getById/{id}")
     public SysLoginUser getById(@PathVariable("id") Long id) {
         // 条件构造器
@@ -101,6 +108,7 @@ public class SysLoginUserController {
      * @description [新增]
      * @author Leocoder
      */
+    @Operation(summary = "新增用户", description = "添加新的系统用户")
     @SaCheckPermission("system:user:add")
     @Transactional(rollbackFor = Exception.class)
     @PostMapping("/sysLoginUser/add")
@@ -127,6 +135,7 @@ public class SysLoginUserController {
      * @description [修改]
      * @author Leocoder
      */
+    @Operation(summary = "修改用户信息", description = "更新系统用户的基本信息")
     @SaCheckPermission("system:user:update")
     @Transactional(rollbackFor = Exception.class)
     @PostMapping("/sysLoginUser/update")
@@ -145,6 +154,7 @@ public class SysLoginUserController {
      * @description [删除]
      * @author Leocoder
      */
+    @Operation(summary = "删除用户", description = "根据用户ID删除指定用户")
     @SaCheckPermission("system:user:delete")
     @Transactional(rollbackFor = Exception.class)
     @PostMapping("/sysLoginUser/deleteById/{id}")
@@ -162,6 +172,7 @@ public class SysLoginUserController {
      * @description [批量删除]
      * @author Leocoder
      */
+    @Operation(summary = "批量删除用户", description = "批量删除多个系统用户")
     @SaCheckPermission("system:user:delete")
     @Transactional(rollbackFor = Exception.class)
     @PostMapping("/sysLoginUser/batchDelete")
@@ -181,6 +192,7 @@ public class SysLoginUserController {
      * @description [修改状态]
      * @author Leocoder
      */
+    @Operation(summary = "修改用户状态", description = "启用或禁用系统用户")
     @PostMapping("/sysLoginUser/updateStatus/{userId}/{userStatus}")
     // @OperLog(value = "修改用户状态", operType = OperType.UPDATE)
     public void update(@PathVariable("userId") Long userId, @PathVariable("userStatus") String userStatus) {
@@ -193,6 +205,7 @@ public class SysLoginUserController {
      * @description [获取登录用户信息、角色、左侧菜单栏(另外一个接口)、按钮等权限]
      * @author Leocoder
      */
+    @Operation(summary = "获取登录用户信息", description = "获取当前登录用户的基本信息、角色和权限")
     @GetMapping("/sysLoginUser/getLoginUserInformation")
     public Map<String, Object> getLoginUserInformation() {
         return sysLoginUserService.getLoginUserInformation();
@@ -202,6 +215,7 @@ public class SysLoginUserController {
      * @description [个人中心-左侧卡片资料数据]
      * @author Leocoder
      */
+    @Operation(summary = "获取个人资料", description = "获取个人中心卡片显示数据")
     @GetMapping("/sysLoginUser/getPersonalData")
     public Map<String, Object> getPersonalData() {
         return sysLoginUserService.getPersonalData();
@@ -211,6 +225,7 @@ public class SysLoginUserController {
      * @description [个人中心-修改基本资料 和 头像]
      * @author Leocoder
      */
+    @Operation(summary = "修改个人资料", description = "修改个人基本信息和头像")
     @PostMapping("/sysLoginUser/updateBasicData")
     // @OperLog(value = "修改个人资料", operType = OperType.UPDATE)
     public void updateBasicData(@RequestBody SysLoginUser sysLoginUser) {
@@ -222,6 +237,7 @@ public class SysLoginUserController {
      * @description [修改密码]
      * @author Leocoder
      */
+    @Operation(summary = "修改登录密码", description = "用户修改自己的登录密码")
     @PostMapping("/sysLoginUser/updateUserPwd")
     // @OperLog(value = "修改密码", operType = OperType.UPDATE, saveRequestData = false, saveResponseData = false)
     public void updateUserPwd(@Validated @RequestBody SysPwdVo vo) {
@@ -253,6 +269,7 @@ public class SysLoginUserController {
      * @description [重置密码]
      * @author Leocoder
      */
+    @Operation(summary = "重置用户密码", description = "管理员重置指定用户的登录密码")
     @SaCheckPermission("system:user:resetPwd")
     @Transactional(rollbackFor = Exception.class)
     @PostMapping("/sysLoginUser/resetPwd/{id}/{password}")
@@ -279,6 +296,7 @@ public class SysLoginUserController {
      * @description [用户下载模版]
      * @author Leocoder
      */
+    @Operation(summary = "下载用户导入模版", description = "下载用户数据导入的Excel模版文件")
     @GetMapping("/sysLoginUser/downloadExcelTemplate")
     // @OperLog(value = "下载用户导入模板", operType = OperType.EXPORT)
     public void downloadExcelTemplate(HttpServletResponse response) {
@@ -290,6 +308,7 @@ public class SysLoginUserController {
      * @description [多条件用户数据导出]
      * @author Leocoder
      */
+    @Operation(summary = "导出用户数据", description = "根据查询条件导出用户数据到Excel文件")
     @SaCheckPermission("system:user:export")
     @GetMapping("/sysLoginUser/exportExcelData")
     // @OperLog(value = "导出用户数据", operType = OperType.EXPORT)
@@ -302,6 +321,7 @@ public class SysLoginUserController {
      * @description [用户数据导入]
      * @author Leocoder
      */
+    @Operation(summary = "导入用户数据", description = "从 Excel文件中批量导入用户数据")
     @SaCheckPermission("system:user:import")
     @Transactional(rollbackFor = Exception.class)
     @PostMapping("/sysLoginUser/importExcelData")

coder-common-thin-web/pom.xml

@@ -26,6 +26,11 @@
             <artifactId>coder-common-thin-system</artifactId>
             <version>${revision}</version>
         </dependency>
+        <!-- SpringDoc OpenAPI 3.0 -->
+        <dependency>
+            <groupId>org.springdoc</groupId>
+            <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
+        </dependency>
         <!-- 定时任务 -->
         <!-- <dependency> -->
         <!--     <groupId>org.leocoder.thin</groupId> -->

coder-common-thin-web/src/main/java/org/leocoder/thin/web/config/OpenApiConfig.java

@@ -0,0 +1,32 @@
+package org.leocoder.thin.web.config;
+
+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 org.springframework.context.annotation.Bean;
+import org.springframework.context.annotation.Configuration;
+
+/**
+ * @author Leocoder
+ * @description OpenAPI 3.0 配置类
+ */
+@Configuration
+public class OpenApiConfig {
+
+    @Bean
+    public OpenAPI customOpenAPI() {
+        return new OpenAPI()
+                .info(new Info()
+                        .title("Coder-Admin 后台管理系统 API 文档")
+                        .description("基于 Spring Boot 3.5.0 的企业级后台管理系统 API 接口文档")
+                        .version("1.0.0")
+                        .contact(new Contact()
+                                .name("Leocoder")
+                                .email("admin@leocoder.org")
+                                .url("https://www.leocoder.org"))
+                        .license(new License()
+                                .name("Apache 2.0")
+                                .url("https://www.apache.org/licenses/LICENSE-2.0.html")));
+    }
+}

coder-common-thin-web/src/main/resources/application-dev.yml

@@ -51,7 +51,7 @@ spring:
       # 端口，默认为6379
       port: 16379
       # 数据库索引
-      database: 0
+      database: 4
       # 密码[若没有密码请注释掉，若有账号密码：则 账号:密码]
       password: coder
       # 连接超时时间
@@ -59,6 +59,29 @@ spring:
       # 是否开启ssl
       ssl.enabled: false
 
+# SpringDoc OpenAPI 3.0 配置
+springdoc:
+  api-docs:
+    # 是否开启 OpenAPI 接口文档
+    enabled: true
+    # OpenAPI 接口文档路径
+    path: /v3/api-docs
+  swagger-ui:
+    # 是否开启 Swagger UI
+    enabled: true
+    # Swagger UI 访问路径
+    path: /swagger-ui.html
+    # 显示 Extensions
+    display-extensions: true
+    # 显示 Common Extensions
+    display-common-extensions: true
+  # 需要扫描的包路径
+  packages-to-scan: org.leocoder.thin
+  # 接口排序方式[method: 按方法名排序, alpha: 按字母排序]
+  swagger-ui.operations-sorter: method
+  # 标签排序方式[alpha: 按字母排序]
+  swagger-ui.tags-sorter: alpha
+
 # 项目配置
 coder:
   # 名称

pom.xml

@@ -51,6 +51,7 @@
         <jodaTime.version>2.14.0</jodaTime.version>
         <captcha.version>1.6.2</captcha.version>
         <freemarker.version>2.3.34</freemarker.version>
+        <springdoc.version>2.7.0</springdoc.version>
 
         <!-- 插件版本 -->
         <maven-compiler-plugin.verison>3.14.0</maven-compiler-plugin.verison>
@@ -209,6 +210,12 @@
                 <artifactId>freemarker</artifactId>
                 <version>${freemarker.version}</version>
             </dependency>
+            <!-- SpringDoc OpenAPI 3.0 -->
+            <dependency>
+                <groupId>org.springdoc</groupId>
+                <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
+                <version>${springdoc.version}</version>
+            </dependency>
         </dependencies>
     </dependencyManagement>