docs(swagger): 添加 swagger 文档

pom.xml

@@ -48,6 +48,13 @@
             <groupId>com.mysql</groupId>
             <artifactId>mysql-connector-j</artifactId>
         </dependency>
+
+        <!--docs-->
+        <dependency>
+            <groupId>org.springdoc</groupId>
+            <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
+            <version>2.0.4</version>
+        </dependency>
     </dependencies>
 
 

src/main/java/org/linker/springboot/config/SwaggerConfiguration.java

+package org.linker.springboot.config;
+
+import io.swagger.v3.oas.models.OpenAPI;
+import io.swagger.v3.oas.models.info.Info;
+import org.springframework.context.annotation.Bean;
+import org.springframework.context.annotation.Configuration;
+
+@Configuration
+public class SwaggerConfiguration {
+
+    @Bean
+    public OpenAPI customOpenAPI() {
+        return new OpenAPI()
+                .info(new Info().title("测试 API")
+                        .version("1.0")
+                        .description("测试 API 描述"));
+    }
+
+}

src/main/java/org/linker/springboot/controller/OtherController.java

+package org.linker.springboot.controller;
+
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.tags.Tag;
+import org.springframework.web.bind.annotation.GetMapping;
+import org.springframework.web.bind.annotation.RequestMapping;
+import org.springframework.web.bind.annotation.RestController;
+
+@RestController
+@RequestMapping("/others")
+@Tag(name = "其他", description = "其他相关接口")
+public class OtherController {
+
+    @GetMapping("/other")
+    @Operation(summary = "其他接口", description = "其他接口描述")
+    public String other() {
+        return "other";
+    }
+}

src/main/java/org/linker/springboot/controller/UserController.java

 package org.linker.springboot.controller;
 
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.Parameter;
+import io.swagger.v3.oas.annotations.media.Schema;
+import io.swagger.v3.oas.annotations.tags.Tag;
 import jakarta.validation.Valid;
 import jakarta.validation.constraints.Min;
 import jakarta.validation.constraints.NotNull;
@@ -27,6 +31,7 @@ import java.util.UUID;
 @RestController
 @RequestMapping("/users")
 @Validated
+@Tag(name = "用户管理", description = "用户管理相关接口")
 public class UserController {
 
     @Autowired
@@ -95,6 +100,9 @@ public class UserController {
      * @return 是否修改成功
      */
     @PutMapping("/{id}")
+    @Operation(summary = "更新用户", description = "根据用户编号更新用户信息")
+    @Parameter(name = "id", description = "用户编号", required = true)
+    @Schema(name = "updateDTO", description = "更新用户信息 DTO")
     public Boolean update(@PathVariable("id") Integer id, UserUpdateDTO updateDTO) {
         // 将 id 设置到 updateDTO 中
         updateDTO.setId(id);
@@ -180,11 +188,14 @@ public class UserController {
     }
 
     @GetMapping("/get_all_users")
+    @Operation(summary = "获取所有用户", description = "从数据库中获取所有用户")
     public CommonResult<List<User>> getAllUsersFromDB() {
         return CommonResult.success(userService.getAllUserFromDB());
     }
 
     @GetMapping("/get_user_by_id")
+    @Operation(summary = "根据用户编号获取用户", description = "根据用户编号获取用户")
+    @Parameter(name = "id", description = "用户编号", required = true)
     public CommonResult<User> getUserById(@Min(value = 1, message = "用户编号必须大于 0") Integer id) {
         return CommonResult.success(userService.getUserById(id));
     }

src/main/resources/application.yml

@@ -8,14 +8,14 @@ spring:
       url: jdbc:mysql://192.168.0.210:3306/springboot_study?useSSL=false&serverTimezone=Asia/Shanghai&allowPublicKeyRetrieval=true&nullCatalogMeansCurrent=true
       username: root
       password: lhr
-      initial-size: 1 # ?????
-      min-idle: 1 # ???????
-      max-active: 20 # ???????
-      max-wait: 600000 # ???????????????????
-      time-between-eviction-runs-millis: 60000 # ???????????????????????????????
-      min-evictable-idle-time-millis: 300000 # ??????????????????????
-      max-evictable-idle-time-millis: 900000 # ??????????????????????
-      validation-query: SELECT 1 FROM DUAL # ??????????
+      initial-size: 1 # 初始连接数
+      min-idle: 1 # 最小连接池数量
+      max-active: 20 # 最大连接池数量
+      max-wait: 600000 # 配置获取连接等待超时的时间，单位：毫秒
+      time-between-eviction-runs-millis: 60000 # 配置间隔多久才进行一次检测，检测需要关闭的空闲连接，单位：毫秒
+      min-evictable-idle-time-millis: 300000 # 配置一个连接在池中最小生存的时间，单位：毫秒
+      max-evictable-idle-time-millis: 900000 # 配置一个连接在池中最大生存的时间，单位：毫秒
+      validation-query: SELECT 1 FROM DUAL # 配置检测连接是否有效
       test-while-idle: true
       test-on-borrow: false
       test-on-return: false
@@ -33,3 +33,8 @@ mybatis-plus:
 logging:
   level:
     org.linker.springboot.mapper: debug
+
+springdoc:
+  api-docs:
+    enabled: true
+  paths-to-match: /users/**