<!-- Swagger3核心依賴 -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-boot-starter</artifactId>
    <version>3.0.0</version>
</dependency>
<!-- 可選：Swagger UI美化依賴（推薦） -->
<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-spring-boot-starter</artifactId>
    <version>3.0.3</version>
</dependency>

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 Swagger3Config {
    // 定義API文檔全局信息
    @Bean
    public OpenAPI customOpenAPI() {
        return new OpenAPI()
                // 文檔標(biāo)題、描述、版本
                .info(new Info()
                        .title("Spring Boot Swagger3 API文檔")
                        .description("基于Swagger3的接口文檔示例，包含用戶管理、訂單管理等模塊")
                        .version("v1.0.0")
                        // 可選：添加聯(lián)系人信息
                        .contact(new io.swagger.v3.oas.models.info.Contact()
                                .name("開發(fā)團(tuán)隊(duì)")
                                .email("dev@example.com")));
    }
}

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import springfox.documentation.oas.annotations.EnableOpenApi;

@SpringBootApplication
@EnableOpenApi // 開啟Swagger3文檔功能
public class Swagger3DemoApplication {
    public static void main(String[] args) {
        SpringApplication.run(Swagger3DemoApplication.class, args);
    }
}

import io.swagger.v3.oas.annotations.tags.Tag;
import org.springframework.web.bind.annotation.RestController;

@RestController
@RequestMapping("/api/user")
// 描述用戶管理模塊
@Tag(name = "用戶管理模塊", description = "提供用戶CRUD操作接口，支持分頁(yè)查詢和條件篩選")
public class UserController {
    // 接口方法...
}

import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.responses.ApiResponse;
import io.swagger.v3.oas.annotations.responses.ApiResponses;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;

@PostMapping("/add")
@Operation(summary = "新增用戶", description = "注意：用戶名需唯一，密碼需加密傳輸")
@ApiResponses({
        @ApiResponse(responseCode = "200", description = "新增成功，返回用戶ID"),
        @ApiResponse(responseCode = "400", description = "參數(shù)錯(cuò)誤（如用戶名為空、格式錯(cuò)誤）"),
        @ApiResponse(responseCode = "500", description = "服務(wù)器異常，新增失敗")
})
public Result<Integer> addUser(@RequestBody UserDTO userDTO) {
    // 業(yè)務(wù)邏輯...
    return Result.success(userId);
}

import io.swagger.v3.oas.annotations.Parameter;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;

@GetMapping("/{userId}")
@Operation(summary = "根據(jù)ID查詢用戶")
public Result<UserVO> getUserById(
        @PathVariable 
        @Parameter(name = "userId", description = "用戶唯一ID", required = true, example = "1001") 
        Integer userId) {
    // 業(yè)務(wù)邏輯...
    return Result.success(userVO);
}

@PostMapping("/update")
@Operation(summary = "更新用戶信息")
public Result<Boolean> updateUser(
        @RequestBody 
        @Parameter(description = "用戶更新信息，userId必傳") 
        UserUpdateDTO userUpdateDTO) {
    // 業(yè)務(wù)邏輯...
    return Result.success(true);
}

import io.swagger.v3.oas.annotations.media.Schema;

import lombok.Data;

@Data

@Schema(title = "用戶新增請(qǐng)求DTO", description = "用于接收前端傳遞的用戶新增參數(shù)")

public class UserDTO {

    @Schema(description = "用戶名（唯一）", required = true, example = "zhangsan", maxLength = 20)

    private String username;

    @Schema(description = "密碼（需加密）", required = true, example = "123456aA", minLength = 8)

    private String password;

    @Schema(description = "用戶年齡", example = "25", minimum = "18", maximum = "60")

    private Integer age;

    @Schema(description = "用戶郵箱", example = "zhangsan@example.com", format = "email")

    private String email;

    // 隱藏不需要在文檔中顯示的字段

    @Schema(hidden = true)

    private String createTime;

}

import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.Parameter;
import io.swagger.v3.oas.annotations.responses.ApiResponse;
import io.swagger.v3.oas.annotations.responses.ApiResponses;
import io.swagger.v3.oas.annotations.tags.Tag;
import org.springframework.web.bind.annotation.*;

@RestController
@RequestMapping("/api/user")
@Tag(name = "用戶管理模塊", description = "提供用戶新增、查詢、更新、刪除接口")
public class UserController {

    @PostMapping("/add")
    @Operation(summary = "新增用戶", description = "用戶名需唯一，密碼長(zhǎng)度≥8且包含大小寫字母")
    @ApiResponses({
            @ApiResponse(responseCode = "200", description = "新增成功"),
            @ApiResponse(responseCode = "400", description = "參數(shù)錯(cuò)誤（如用戶名重復(fù)）"),
            @ApiResponse(responseCode = "500", description = "服務(wù)器異常")
    })
    public Result<Integer> addUser(@RequestBody @Parameter(description = "用戶新增參數(shù)") UserDTO userDTO) {
        // 模擬業(yè)務(wù)邏輯：生成用戶ID
        int userId = 1001;
        return Result.success(userId);
    }

    @GetMapping("/{userId}")
    @Operation(summary = "根據(jù)ID查詢用戶")
    public Result<UserVO> getUserById(
            @PathVariable 
            @Parameter(name = "userId", description = "用戶ID", required = true, example = "1001") 
            Integer userId) {
        // 模擬查詢結(jié)果
        UserVO userVO = new UserVO();
        userVO.setUserId(userId);
        userVO.setUsername("zhangsan");
        userVO.setAge(25);
        userVO.setEmail("zhangsan@example.com");
        return Result.success(userVO);
    }
}

// UserDTO（請(qǐng)求體）
@Data
@Schema(title = "用戶新增DTO", description = "前端新增用戶時(shí)傳遞的參數(shù)")
public class UserDTO {
    @Schema(description = "用戶名", required = true, example = "zhangsan", maxLength = 20)
    private String username;

    @Schema(description = "密碼", required = true, example = "123456aA", minLength = 8)
    private String password;

    @Schema(description = "年齡", example = "25", minimum = "18")
    private Integer age;
}

// UserVO（響應(yīng)體）
@Data
@Schema(title = "用戶查詢VO", description = "后端返回給前端的用戶信息")
public class UserVO {
    @Schema(description = "用戶ID", example = "1001")
    private Integer userId;

    @Schema(description = "用戶名", example = "zhangsan")
    private String username;

    @Schema(description = "年齡", example = "25")
    private Integer age;

    @Schema(description = "郵箱", example = "zhangsan@example.com")
    private String email;
}

springfox:

 documentation:

   enabled: false