首页 > 软件编程 > java > Spring Boot Swagger3常用注解

Spring Boot Swagger3常用注解详解与实战指南

2025-10-30 11:19:46 作者：VarYa

Swagger是一个用于设计、构建、文档化和使用RESTful Web服务的开源工具,Swagger3是Swagger的最新版本,它提供了许多新功能和改进,这篇文章主要介绍了Spring Boot Swagger3常用注解详解与实战指南的相关资料,需要的朋友可以参考下

前言

在 Spring Boot 项目开发中，API 文档是前后端协作、项目维护的重要工具。Swagger3（OpenAPI 3.0）作为主流的 API 文档生成工具，通过简单的注解就能快速生成规范化的 API 文档，极大提升开发效率。本文将详细介绍 Spring Boot 整合 Swagger3 的核心注解及实战用法。

一、Swagger3 环境搭建（基础准备）

在使用注解前，需先完成 Spring Boot 与 Swagger3 的整合，步骤如下：

1. 引入依赖（Maven）

根据 Spring Boot 版本选择对应依赖（Spring Boot 2.x/3.x 通用，3.x 需确保 JDK≥11）：

<!-- 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>

2. 配置 Swagger3 核心类

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()
                // 文档标题、描述、版本
                .info(new Info()
                        .title("Spring Boot Swagger3 API文档")
                        .description("基于Swagger3的接口文档示例，包含用户管理、订单管理等模块")
                        .version("v1.0.0")
                        // 可选：添加联系人信息
                        .contact(new io.swagger.v3.oas.models.info.Contact()
                                .name("开发团队")
                                .email("dev@example.com")));
    }
}

3. 启动类开启 Swagger3

在 Spring Boot 启动类上添加@EnableOpenApi注解（Swagger3 专用，替代 Swagger2 的@EnableSwagger2）：

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);
    }
}

4. 访问 Swagger UI

原生 Swagger UI：http://localhost:8080/swagger-ui/index.html
Knife4j 美化 UI（推荐）：http://localhost:8080/doc.html

二、Swagger3 核心注解详解

Swagger3 注解分为接口类注解、接口方法注解、参数注解、实体类注解四大类，以下是最常用的 10 个注解：

1. 接口类注解（Controller 层）

@Tag：描述 Controller 类

用于定义 Controller 的功能模块，相当于接口分组，属性如下：

属性名	作用	示例值
name	模块名称（必填）	“用户管理模块”
description	模块描述（可选）	“包含用户新增、查询、删除接口”
order	排序序号（可选）	1（数字越小越靠前）

使用示例：

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

@RestController
@RequestMapping("/api/user")
// 描述用户管理模块
@Tag(name = "用户管理模块", description = "提供用户CRUD操作接口，支持分页查询和条件筛选")
public class UserController {
    // 接口方法...
}

2. 接口方法注解（Controller 方法）

@Operation：描述接口方法

定义单个接口的功能、请求方式等核心信息，是方法级最核心的注解：

属性名	作用	示例值
summary	接口简短描述（必填）	“新增用户”
description	接口详细描述（可选）	“传入用户信息，创建新用户，返回用户 ID”
method	请求方式（可选）	“POST”（默认自动识别）
hidden	是否隐藏接口（可选）	false（true 不显示在文档）

@ApiResponses & @ApiResponse：描述接口响应

定义接口的多组响应状态（如成功、参数错误、服务器异常）：

@ApiResponses：用于包裹多个@ApiResponse
@ApiResponse：单个响应状态配置

使用示例：

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 = "参数错误（如用户名为空、格式错误）"),
        @ApiResponse(responseCode = "500", description = "服务器异常，新增失败")
})
public Result<Integer> addUser(@RequestBody UserDTO userDTO) {
    // 业务逻辑...
    return Result.success(userId);
}

3. 参数注解（方法参数 / 请求体）

@Parameter：描述单个参数

用于方法的单个参数（如路径参数、请求参数），支持指定参数说明、是否必传等：

属性名	作用	示例值
name	参数名（必填）	“userId”
description	参数描述（可选）	“用户 ID，用于查询单个用户”
required	是否必传（可选）	true（默认 false）
example	示例值（可选）	“1001”

使用示例（路径参数）：

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 = "根据ID查询用户")
public Result<UserVO> getUserById(
        @PathVariable 
        @Parameter(name = "userId", description = "用户唯一ID", required = true, example = "1001") 
        Integer userId) {
    // 业务逻辑...
    return Result.success(userVO);
}

@RequestBody：描述请求体参数

用于标记请求体参数（通常是 JSON 格式），并关联实体类的@Schema注解：

使用示例：

@PostMapping("/update")
@Operation(summary = "更新用户信息")
public Result<Boolean> updateUser(
        @RequestBody 
        @Parameter(description = "用户更新信息，userId必传") 
        UserUpdateDTO userUpdateDTO) {
    // 业务逻辑...
    return Result.success(true);
}

4. 实体类注解（DTO/VO 层）

@Schema：描述实体类 / 字段

用于定义实体类（如 DTO、VO）及其字段的文档说明，替代 Swagger2 的@ApiModel和@ApiModelProperty：

属性名	作用	示例值
title	实体类描述（类级别）	“用户新增请求 DTO”
description	字段描述（字段级别）	“用户名，长度 1-20 字符”
required	字段是否必传（可选）	true（默认 false）
example	字段示例值（可选）	“zhangsan”
hidden	是否隐藏字段（可选）	false（true 不显示在文档）
format	字段格式（可选）	“email”（如邮箱格式校验）

使用示例（实体类）：

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

import lombok.Data;

@Data

@Schema(title = "用户新增请求DTO", description = "用于接收前端传递的用户新增参数")

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;

}

三、实战案例：完整接口文档示例

结合上述注解，实现一个 “用户管理” 模块的完整 API 文档，效果如下：

1. Controller 层（UserController）

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 = "用户名需唯一，密码长度≥8且包含大小写字母")
    @ApiResponses({
            @ApiResponse(responseCode = "200", description = "新增成功"),
            @ApiResponse(responseCode = "400", description = "参数错误（如用户名重复）"),
            @ApiResponse(responseCode = "500", description = "服务器异常")
    })
    public Result<Integer> addUser(@RequestBody @Parameter(description = "用户新增参数") UserDTO userDTO) {
        // 模拟业务逻辑：生成用户ID
        int userId = 1001;
        return Result.success(userId);
    }

    @GetMapping("/{userId}")
    @Operation(summary = "根据ID查询用户")
    public Result<UserVO> getUserById(
            @PathVariable 
            @Parameter(name = "userId", description = "用户ID", required = true, example = "1001") 
            Integer userId) {
        // 模拟查询结果
        UserVO userVO = new UserVO();
        userVO.setUserId(userId);
        userVO.setUsername("zhangsan");
        userVO.setAge(25);
        userVO.setEmail("zhangsan@example.com");
        return Result.success(userVO);
    }
}

2. 实体类（UserDTO & UserVO）

// UserDTO（请求体）
@Data
@Schema(title = "用户新增DTO", description = "前端新增用户时传递的参数")
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（响应体）
@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;
}

3. 访问文档效果

启动项目后，访问http://localhost:8080/doc.html，可看到：

左侧菜单显示 “用户管理模块” 分组
展开分组可看到/api/user/add和/api/user/{userId}两个接口
点击接口可查看参数说明、响应状态、实体类字段详情
支持在线调试（填写参数后点击 “发送” 按钮测试接口）

四、注意事项与最佳实践

生产环境关闭 Swagger避免接口暴露，在application-prod.yml中配置：

springfox:

 documentation:

   enabled: false

注解属性简化非必填属性（如description）可根据需求省略，优先保证name、summary、required等核心属性。
参数示例规范化example属性需填写真实场景的值（如邮箱格式、手机号格式），避免填写 “test” 等无意义值。
实体类复用同一实体类在不同接口中（如新增和更新），可通过@Schema(hidden = true)隐藏不需要的字段，无需重复创建实体类。

五、总结

类级别：@Tag（分组描述）
方法级别：@Operation（接口描述）、@ApiResponses（响应描述）
参数级别：@Parameter（单个参数）、@RequestBody（请求体）
实体类级别：@Schema（字段描述）

掌握这些注解后，结合 Spring Boot 可快速生成规范化、可调试的 API 文档，提升前后端协作效率。建议在项目初期就引入 Swagger3，并保持注解与业务逻辑同步更新。

到此这篇关于Spring Boot Swagger3常用注解详解与实战指南的文章就介绍到这了,更多相关Spring Boot Swagger3常用注解内容请搜索脚本之家以前的文章或继续浏览下面的相关文章希望大家以后多多支持脚本之家！

Spring Boot Swagger3常用注解详解与实战指南

前言

一、Swagger3 环境搭建（基础准备）

1. 引入依赖（Maven）

2. 配置 Swagger3 核心类

3. 启动类开启 Swagger3

4. 访问 Swagger UI

二、Swagger3 核心注解详解

1. 接口类注解（Controller 层）

@Tag：描述 Controller 类

2. 接口方法注解（Controller 方法）

@Operation：描述接口方法

@ApiResponses & @ApiResponse：描述接口响应

3. 参数注解（方法参数 / 请求体）

@Parameter：描述单个参数

@RequestBody：描述请求体参数

4. 实体类注解（DTO/VO 层）

@Schema：描述实体类 / 字段

三、实战案例：完整接口文档示例

1. Controller 层（UserController）

2. 实体类（UserDTO & UserVO）

3. 访问文档效果

四、注意事项与最佳实践

五、总结

您可能感兴趣的文章: