深入浅出Swagger注解示例代码从入门到精通的完整指南涵盖常用注解详解实际应用场景助你快速提升API开发能力

威震华夏关云长

引言

Swagger是一个强大且广泛使用的API开发工具集，它使得设计和文档化RESTful API变得更加简单。通过Swagger注解，开发者可以直接在代码中描述API，从而自动生成交互式API文档，提高开发效率和团队协作能力。本文将深入浅出地介绍Swagger注解的使用，从基础概念到高级应用，帮助你全面掌握Swagger，提升API开发能力。

Swagger基础知识

Swagger是一个规范和完整的框架，用于生成、描述、调用和可视化RESTful风格的Web服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法、参数和模型紧密集成到服务器端的代码中，允许API始终保持同步。

在Java项目中，我们通常使用Springfox或SpringDoc来实现Swagger集成。Springfox适用于较早的Spring Boot版本，而SpringDoc则支持Spring Boot 2.x和3.x以及OpenAPI 3规范。本文将以SpringDoc为例进行讲解，因为它代表了未来的发展方向。

首先，我们需要在项目中添加Swagger依赖：

2. <!-- 对于Maven项目 -->
3. <dependency>
4.     <groupId>org.springdoc</groupId>
5.     <artifactId>springdoc-openapi-ui</artifactId>
6.     <version>1.6.14</version>
7. </dependency>

复制代码

或者对于Gradle项目：

2. implementation 'org.springdoc:springdoc-openapi-ui:1.6.14'

复制代码

添加依赖后，我们可以通过访问http://localhost:8080/swagger-ui.html来查看Swagger UI界面。

Swagger常用注解详解

Swagger提供了丰富的注解来描述API。这些注解可以分为类级别、方法级别、参数级别和模型级别。下面我们详细介绍这些注解及其用法。

类级别注解

@Tag注解用于在控制器类上，为API分组提供名称和描述。

2. import io.swagger.v3.oas.annotations.tags.Tag;
4. @Tag(name = "用户管理", description = "用户相关的API操作")
5. @RestController
6. @RequestMapping("/api/users")
7. public class UserController {
8.     // 控制器方法
9. }

复制代码

在Swagger UI中，这个控制器下的所有API都会被归类到”用户管理”标签下，并显示描述信息。

@SecurityScheme注解用于定义安全方案，如API密钥、OAuth2等。

2. import io.swagger.v3.oas.annotations.enums.SecuritySchemeType;
3. import io.swagger.v3.oas.annotations.security.SecurityScheme;
5. @SecurityScheme(
6.     name = "bearerAuth",
7.     type = SecuritySchemeType.HTTP,
8.     bearerFormat = "JWT",
9.     scheme = "bearer"
10. )
11. @SpringBootApplication
12. public class MyApp {
13.     public static void main(String[] args) {
14.         SpringApplication.run(MyApp.class, args);
15.     }
16. }

复制代码

这个配置定义了一个名为”bearerAuth”的JWT认证方案。

方法级别注解

@Operation注解用于描述单个API操作，包括摘要、详细描述等。

2. import io.swagger.v3.oas.annotations.Operation;
3. import io.swagger.v3.oas.annotations.responses.ApiResponse;
4. import io.swagger.v3.oas.annotations.responses.ApiResponses;
6. @Operation(
7.     summary = "获取用户信息",
8.     description = "根据用户ID获取用户的详细信息",
9.     tags = { "用户管理" }
10. )
11. @ApiResponses(value = {
12.     @ApiResponse(responseCode = "200", description = "成功获取用户信息"),
13.     @ApiResponse(responseCode = "404", description = "用户不存在"),
14.     @ApiResponse(responseCode = "500", description = "服务器内部错误")
15. })
16. @GetMapping("/{id}")
17. public ResponseEntity<User> getUserById(@PathVariable Long id) {
18.     // 方法实现
19. }

复制代码

@ApiResponse注解用于描述API可能的响应。通常与@ApiResponses一起使用，可以定义多个响应。

2. @ApiResponses(value = {
3.     @ApiResponse(responseCode = "200", description = "成功获取用户信息",
4.         content = { @Content(mediaType = "application/json",
5.             schema = @Schema(implementation = User.class)) }),
6.     @ApiResponse(responseCode = "404", description = "用户不存在",
7.         content = @Content),
8.     @ApiResponse(responseCode = "500", description = "服务器内部错误",
9.         content = @Content)
10. })
11. @GetMapping("/{id}")
12. public ResponseEntity<User> getUserById(@PathVariable Long id) {
13.     // 方法实现
14. }

复制代码

@Parameters注解用于描述API的所有参数。当有多个参数需要描述时，可以使用此注解。

2. import io.swagger.v3.oas.annotations.Parameter;
3. import io.swagger.v3.oas.annotations.Parameters;
5. @Parameters({
6.     @Parameter(name = "id", description = "用户ID", required = true, example = "1"),
7.     @Parameter(name = "fields", description = "需要返回的字段，多个字段用逗号分隔",
8.                required = false, example = "id,name,email")
9. })
10. @GetMapping("/{id}")
11. public ResponseEntity<User> getUserById(
12.     @PathVariable Long id,
13.     @RequestParam(required = false) String fields) {
14.     // 方法实现
15. }

复制代码

参数级别注解

@Parameter注解用于描述方法参数，包括名称、描述、是否必需等。

2. @GetMapping("/search")
3. public ResponseEntity<List<User>> searchUsers(
4.     @Parameter(description = "搜索关键词", required = true, example = "john")
5.     @RequestParam String keyword,
6.    
7.     @Parameter(description = "页码", required = false, example = "1")
8.     @RequestParam(defaultValue = "1") int page,
9.    
10.     @Parameter(description = "每页大小", required = false, example = "10")
11.     @RequestParam(defaultValue = "10") int size) {
12.     // 方法实现
13. }

复制代码

@RequestBody注解与@Content和@Schema结合使用，用于描述请求体。

2. import io.swagger.v3.oas.annotations.media.Content;
3. import io.swagger.v3.oas.annotations.media.Schema;
4. import io.swagger.v3.oas.annotations.parameters.RequestBody;
6. @Operation(summary = "创建用户", description = "创建一个新的用户")
7. @PostMapping("/")
8. public ResponseEntity<User> createUser(
9.     @RequestBody(description = "用户信息", required = true,
10.         content = @Content(
11.             mediaType = "application/json",
12.             schema = @Schema(implementation = UserCreateRequest.class)
13.         )
14.     )
15.     @Valid @RequestBody UserCreateRequest userRequest) {
16.     // 方法实现
17. }

复制代码

模型注解

@Schema注解用于描述模型类及其属性。

2. import io.swagger.v3.oas.annotations.media.Schema;
4. @Schema(description = "用户信息")
5. public class User {
6.    
7.     @Schema(description = "用户ID", example = "1", requiredMode = Schema.RequiredMode.REQUIRED)
8.     private Long id;
9.    
10.     @Schema(description = "用户名", example = "john_doe", requiredMode = Schema.RequiredMode.REQUIRED)
11.     private String username;
12.    
13.     @Schema(description = "电子邮箱", example = "john.doe@example.com", requiredMode = Schema.RequiredMode.REQUIRED)
14.     private String email;
15.    
16.     @Schema(description = "创建时间", example = "2023-01-01T12:00:00Z", requiredMode = Schema.RequiredMode.NOT_REQUIRED)
17.     private LocalDateTime createdAt;
18.    
19.     // getters and setters
20. }

复制代码

@ArraySchema注解用于描述数组类型的模型。

2. @ArraySchema(schema = @Schema(implementation = User.class))
3. private List<User> users;

复制代码

实际应用场景与示例

场景一：构建用户管理API

让我们通过一个完整的用户管理API示例，展示如何在实际项目中应用Swagger注解。

首先，定义用户模型：

2. import io.swagger.v3.oas.annotations.media.Schema;
3. import java.time.LocalDateTime;
5. @Schema(description = "用户信息")
6. public class User {
7.    
8.     @Schema(description = "用户ID", example = "1", requiredMode = Schema.RequiredMode.REQUIRED)
9.     private Long id;
10.    
11.     @Schema(description = "用户名", example = "john_doe", requiredMode = Schema.RequiredMode.REQUIRED)
12.     private String username;
13.    
14.     @Schema(description = "电子邮箱", example = "john.doe@example.com", requiredMode = Schema.RequiredMode.REQUIRED)
15.     private String email;
16.    
17.     @Schema(description = "手机号码", example = "13800138000", requiredMode = Schema.RequiredMode.NOT_REQUIRED)
18.     private String phone;
19.    
20.     @Schema(description = "用户状态", example = "ACTIVE", requiredMode = Schema.RequiredMode.REQUIRED)
21.     private UserStatus status;
22.    
23.     @Schema(description = "创建时间", example = "2023-01-01T12:00:00Z", requiredMode = Schema.RequiredMode.NOT_REQUIRED)
24.     private LocalDateTime createdAt;
25.    
26.     @Schema(description = "更新时间", example = "2023-01-01T12:00:00Z", requiredMode = Schema.RequiredMode.NOT_REQUIRED)
27.     private LocalDateTime updatedAt;
28.    
29.     // 枚举定义用户状态
30.     public enum UserStatus {
31.         ACTIVE, INACTIVE, DISABLED
32.     }
33.    
34.     // getters and setters
35. }

复制代码

然后，定义创建用户的请求DTO：

2. import io.swagger.v3.oas.annotations.media.Schema;
3. import javax.validation.constraints.Email;
4. import javax.validation.constraints.NotBlank;
5. import javax.validation.constraints.Pattern;
6. import javax.validation.constraints.Size;
8. @Schema(description = "创建用户请求")
9. public class UserCreateRequest {
10.    
11.     @NotBlank(message = "用户名不能为空")
12.     @Size(min = 3, max = 20, message = "用户名长度必须在3到20个字符之间")
13.     @Schema(description = "用户名", example = "john_doe", requiredMode = Schema.RequiredMode.REQUIRED)
14.     private String username;
15.    
16.     @NotBlank(message = "电子邮箱不能为空")
17.     @Email(message = "电子邮箱格式不正确")
18.     @Schema(description = "电子邮箱", example = "john.doe@example.com", requiredMode = Schema.RequiredMode.REQUIRED)
19.     private String email;
20.    
21.     @Pattern(regexp = "^1[3-9]\\d{9}$", message = "手机号码格式不正确")
22.     @Schema(description = "手机号码", example = "13800138000", requiredMode = Schema.RequiredMode.NOT_REQUIRED)
23.     private String phone;
24.    
25.     @Schema(description = "密码", example = "Password123!", requiredMode = Schema.RequiredMode.REQUIRED)
26.     private String password;
27.    
28.     // getters and setters
29. }

复制代码

定义更新用户的请求DTO：

2. import io.swagger.v3.oas.annotations.media.Schema;
4. @Schema(description = "更新用户请求")
5. public class UserUpdateRequest {
6.    
7.     @Schema(description = "电子邮箱", example = "john.doe@example.com", requiredMode = Schema.RequiredMode.NOT_REQUIRED)
8.     private String email;
9.    
10.     @Schema(description = "手机号码", example = "13800138000", requiredMode = Schema.RequiredMode.NOT_REQUIRED)
11.     private String phone;
12.    
13.     @Schema(description = "用户状态", example = "ACTIVE", requiredMode = Schema.RequiredMode.NOT_REQUIRED)
14.     private User.UserStatus status;
15.    
16.     // getters and setters
17. }

复制代码

现在，创建用户控制器：

2. import io.swagger.v3.oas.annotations.Operation;
3. import io.swagger.v3.oas.annotations.Parameter;
4. import io.swagger.v3.oas.annotations.media.Content;
5. import io.swagger.v3.oas.annotations.media.Schema;
6. import io.swagger.v3.oas.annotations.responses.ApiResponse;
7. import io.swagger.v3.oas.annotations.responses.ApiResponses;
8. import io.swagger.v3.oas.annotations.security.SecurityRequirement;
9. import io.swagger.v3.oas.annotations.tags.Tag;
10. import org.springframework.http.ResponseEntity;
11. import org.springframework.web.bind.annotation.*;
13. import javax.validation.Valid;
14. import java.util.List;
16. @Tag(name = "用户管理", description = "用户相关的API操作")
17. @RestController
18. @RequestMapping("/api/users")
19. @SecurityRequirement(name = "bearerAuth")
20. public class UserController {
22.     private final UserService userService;
24.     public UserController(UserService userService) {
25.         this.userService = userService;
26.     }
28.     @Operation(
29.         summary = "创建用户",
30.         description = "创建一个新的用户账户"
31.     )
32.     @ApiResponses(value = {
33.         @ApiResponse(responseCode = "201", description = "用户创建成功",
34.             content = { @Content(mediaType = "application/json",
35.                 schema = @Schema(implementation = User.class)) }),
36.         @ApiResponse(responseCode = "400", description = "请求参数不正确",
37.             content = @Content),
38.         @ApiResponse(responseCode = "409", description = "用户名或邮箱已存在",
39.             content = @Content)
40.     })
41.     @PostMapping("/")
42.     public ResponseEntity<User> createUser(
43.         @Parameter(description = "用户信息", required = true)
44.         @Valid @RequestBody UserCreateRequest userRequest) {
45.         User createdUser = userService.createUser(userRequest);
46.         return ResponseEntity.status(201).body(createdUser);
47.     }
49.     @Operation(
50.         summary = "获取用户",
51.         description = "根据用户ID获取用户详细信息"
52.     )
53.     @ApiResponses(value = {
54.         @ApiResponse(responseCode = "200", description = "成功获取用户信息",
55.             content = { @Content(mediaType = "application/json",
56.                 schema = @Schema(implementation = User.class)) }),
57.         @ApiResponse(responseCode = "404", description = "用户不存在",
58.             content = @Content)
59.     })
60.     @GetMapping("/{id}")
61.     public ResponseEntity<User> getUserById(
62.         @Parameter(description = "用户ID", required = true, example = "1")
63.         @PathVariable Long id) {
64.         User user = userService.getUserById(id);
65.         return ResponseEntity.ok(user);
66.     }
68.     @Operation(
69.         summary = "更新用户",
70.         description = "根据用户ID更新用户信息"
71.     )
72.     @ApiResponses(value = {
73.         @ApiResponse(responseCode = "200", description = "用户更新成功",
74.             content = { @Content(mediaType = "application/json",
75.                 schema = @Schema(implementation = User.class)) }),
76.         @ApiResponse(responseCode = "400", description = "请求参数不正确",
77.             content = @Content),
78.         @ApiResponse(responseCode = "404", description = "用户不存在",
79.             content = @Content)
80.     })
81.     @PutMapping("/{id}")
82.     public ResponseEntity<User> updateUser(
83.         @Parameter(description = "用户ID", required = true, example = "1")
84.         @PathVariable Long id,
85.         @Parameter(description = "更新信息", required = true)
86.         @Valid @RequestBody UserUpdateRequest userRequest) {
87.         User updatedUser = userService.updateUser(id, userRequest);
88.         return ResponseEntity.ok(updatedUser);
89.     }
91.     @Operation(
92.         summary = "删除用户",
93.         description = "根据用户ID删除用户"
94.     )
95.     @ApiResponses(value = {
96.         @ApiResponse(responseCode = "204", description = "用户删除成功",
97.             content = @Content),
98.         @ApiResponse(responseCode = "404", description = "用户不存在",
99.             content = @Content)
100.     })
101.     @DeleteMapping("/{id}")
102.     public ResponseEntity<Void> deleteUser(
103.         @Parameter(description = "用户ID", required = true, example = "1")
104.         @PathVariable Long id) {
105.         userService.deleteUser(id);
106.         return ResponseEntity.noContent().build();
107.     }
109.     @Operation(
110.         summary = "获取用户列表",
111.         description = "分页获取用户列表，支持按关键词搜索"
112.     )
113.     @ApiResponses(value = {
114.         @ApiResponse(responseCode = "200", description = "成功获取用户列表",
115.             content = { @Content(mediaType = "application/json",
116.                 schema = @Schema(implementation = PageResult.class)) })
117.     })
118.     @GetMapping("/")
119.     public ResponseEntity<PageResult<User>> getUsers(
120.         @Parameter(description = "页码", required = false, example = "1")
121.         @RequestParam(defaultValue = "1") int page,
122.         
123.         @Parameter(description = "每页大小", required = false, example = "10")
124.         @RequestParam(defaultValue = "10") int size,
125.         
126.         @Parameter(description = "搜索关键词", required = false, example = "john")
127.         @RequestParam(required = false) String keyword,
128.         
129.         @Parameter(description = "用户状态过滤", required = false, example = "ACTIVE")
130.         @RequestParam(required = false) User.UserStatus status) {
131.         
132.         PageResult<User> users = userService.getUsers(page, size, keyword, status);
133.         return ResponseEntity.ok(users);
134.     }
135. }

复制代码

最后，定义分页结果模型：

2. import io.swagger.v3.oas.annotations.media.Schema;
3. import java.util.List;
5. @Schema(description = "分页结果")
6. public class PageResult<T> {
7.    
8.     @Schema(description = "数据列表", requiredMode = Schema.RequiredMode.REQUIRED)
9.     private List<T> content;
10.    
11.     @Schema(description = "当前页码", example = "1", requiredMode = Schema.RequiredMode.REQUIRED)
12.     private int pageNumber;
13.    
14.     @Schema(description = "每页大小", example = "10", requiredMode = Schema.RequiredMode.REQUIRED)
15.     private int pageSize;
16.    
17.     @Schema(description = "总记录数", example = "100", requiredMode = Schema.RequiredMode.REQUIRED)
18.     private long totalElements;
19.    
20.     @Schema(description = "总页数", example = "10", requiredMode = Schema.RequiredMode.REQUIRED)
21.     private int totalPages;
22.    
23.     @Schema(description = "是否有下一页", example = "true", requiredMode = Schema.RequiredMode.REQUIRED)
24.     private boolean hasNext;
25.    
26.     @Schema(description = "是否有上一页", example = "false", requiredMode = Schema.RequiredMode.REQUIRED)
27.     private boolean hasPrevious;
28.    
29.     // getters and setters
30. }

复制代码

场景二：构建文件上传API

文件上传是Web应用中常见的功能，下面展示如何使用Swagger注解描述文件上传API。

2. import io.swagger.v3.oas.annotations.Operation;
3. import io.swagger.v3.oas.annotations.Parameter;
4. import io.swagger.v3.oas.annotations.media.Content;
5. import io.swagger.v3.oas.annotations.media.Schema;
6. import io.swagger.v3.oas.annotations.responses.ApiResponse;
7. import io.swagger.v3.oas.annotations.tags.Tag;
8. import org.springframework.http.MediaType;
9. import org.springframework.http.ResponseEntity;
10. import org.springframework.web.bind.annotation.*;
11. import org.springframework.web.multipart.MultipartFile;
13. import java.util.HashMap;
14. import java.util.Map;
16. @Tag(name = "文件管理", description = "文件上传和下载相关的API操作")
17. @RestController
18. @RequestMapping("/api/files")
19. @SecurityRequirement(name = "bearerAuth")
20. public class FileController {
22.     @Operation(
23.         summary = "上传文件",
24.         description = "上传单个文件，支持图片、文档等格式"
25.     )
26.     @ApiResponses(value = {
27.         @ApiResponse(responseCode = "200", description = "文件上传成功",
28.             content = { @Content(mediaType = "application/json",
29.                 schema = @Schema(implementation = FileUploadResult.class)) }),
30.         @ApiResponse(responseCode = "400", description = "请求参数不正确",
31.             content = @Content)
32.     })
33.     @PostMapping(value = "/upload", consumes = MediaType.MULTIPART_FORM_DATA_VALUE)
34.     public ResponseEntity<FileUploadResult> uploadFile(
35.         @Parameter(description = "要上传的文件", required = true)
36.         @RequestParam("file") MultipartFile file,
37.         
38.         @Parameter(description = "文件分类", required = false, example = "image")
39.         @RequestParam(required = false) String category) {
40.         
41.         // 模拟文件上传处理
42.         String fileId = "file_" + System.currentTimeMillis();
43.         String fileName = file.getOriginalFilename();
44.         long fileSize = file.getSize();
45.         String contentType = file.getContentType();
46.         
47.         FileUploadResult result = new FileUploadResult(fileId, fileName, fileSize, contentType, category);
48.         return ResponseEntity.ok(result);
49.     }
51.     @Operation(
52.         summary = "批量上传文件",
53.         description = "一次上传多个文件"
54.     )
55.     @ApiResponses(value = {
56.         @ApiResponse(responseCode = "200", description = "文件上传成功",
57.             content = { @Content(mediaType = "application/json",
58.                 schema = @Schema(implementation = FileUploadResult.class)) }),
59.         @ApiResponse(responseCode = "400", description = "请求参数不正确",
60.             content = @Content)
61.     })
62.     @PostMapping(value = "/batch-upload", consumes = MediaType.MULTIPART_FORM_DATA_VALUE)
63.     public ResponseEntity<List<FileUploadResult>> batchUploadFiles(
64.         @Parameter(description = "要上传的文件列表", required = true)
65.         @RequestParam("files") MultipartFile[] files,
66.         
67.         @Parameter(description = "文件分类", required = false, example = "image")
68.         @RequestParam(required = false) String category) {
69.         
70.         // 模拟批量文件上传处理
71.         List<FileUploadResult> results = new ArrayList<>();
72.         for (MultipartFile file : files) {
73.             String fileId = "file_" + System.currentTimeMillis();
74.             String fileName = file.getOriginalFilename();
75.             long fileSize = file.getSize();
76.             String contentType = file.getContentType();
77.             
78.             results.add(new FileUploadResult(fileId, fileName, fileSize, contentType, category));
79.         }
80.         
81.         return ResponseEntity.ok(results);
82.     }
84.     @Operation(
85.         summary = "下载文件",
86.         description = "根据文件ID下载文件"
87.     )
88.     @ApiResponses(value = {
89.         @ApiResponse(responseCode = "200", description = "文件下载成功",
90.             content = { @Content(mediaType = "application/octet-stream") }),
91.         @ApiResponse(responseCode = "404", description = "文件不存在",
92.             content = @Content)
93.     })
94.     @GetMapping("/download/{fileId}")
95.     public ResponseEntity<byte[]> downloadFile(
96.         @Parameter(description = "文件ID", required = true, example = "file_123456789")
97.         @PathVariable String fileId) {
98.         
99.         // 模拟文件下载处理
100.         byte[] fileContent = "Mock file content".getBytes();
101.         String filename = "example.txt";
102.         
103.         return ResponseEntity.ok()
104.                 .header("Content-Disposition", "attachment; filename="" + filename + """)
105.                 .contentType(MediaType.APPLICATION_OCTET_STREAM)
106.                 .body(fileContent);
107.     }
108. }
110. // 文件上传结果模型
111. @Schema(description = "文件上传结果")
112. class FileUploadResult {
113.    
114.     @Schema(description = "文件ID", example = "file_123456789", requiredMode = Schema.RequiredMode.REQUIRED)
115.     private String fileId;
116.    
117.     @Schema(description = "文件名", example = "example.jpg", requiredMode = Schema.RequiredMode.REQUIRED)
118.     private String fileName;
119.    
120.     @Schema(description = "文件大小（字节）", example = "10240", requiredMode = Schema.RequiredMode.REQUIRED)
121.     private long fileSize;
122.    
123.     @Schema(description = "文件类型", example = "image/jpeg", requiredMode = Schema.RequiredMode.REQUIRED)
124.     private String contentType;
125.    
126.     @Schema(description = "文件分类", example = "image", requiredMode = Schema.RequiredMode.NOT_REQUIRED)
127.     private String category;
128.    
129.     @Schema(description = "文件URL", example = "http://example.com/files/file_123456789", requiredMode = Schema.RequiredMode.REQUIRED)
130.     private String url;
131.    
132.     public FileUploadResult(String fileId, String fileName, long fileSize, String contentType, String category) {
133.         this.fileId = fileId;
134.         this.fileName = fileName;
135.         this.fileSize = fileSize;
136.         this.contentType = contentType;
137.         this.category = category;
138.         this.url = "http://example.com/files/" + fileId;
139.     }
140.    
141.     // getters and setters
142. }

复制代码

场景三：构建带权限控制的API

在实际应用中，很多API需要权限控制。下面展示如何使用Swagger注解描述带权限控制的API。

首先，定义角色枚举：

2. import io.swagger.v3.oas.annotations.media.Schema;
4. @Schema(description = "用户角色")
5. public enum UserRole {
6.     @Schema(description = "管理员")
7.     ADMIN,
8.    
9.     @Schema(description = "普通用户")
10.     USER,
11.    
12.     @Schema(description = "访客")
13.     GUEST
14. }

复制代码

然后，创建带权限控制的API控制器：

2. import io.swagger.v3.oas.annotations.Operation;
3. import io.swagger.v3.oas.annotations.Parameter;
4. import io.swagger.v3.oas.annotations.enums.SecuritySchemeIn;
5. import io.swagger.v3.oas.annotations.enums.SecuritySchemeType;
6. import io.swagger.v3.oas.annotations.media.Content;
7. import io.swagger.v3.oas.annotations.media.Schema;
8. import io.swagger.v3.oas.annotations.responses.ApiResponse;
9. import io.swagger.v3.oas.annotations.security.SecurityRequirement;
10. import io.swagger.v3.oas.annotations.security.SecurityScheme;
11. import io.swagger.v3.oas.annotations.tags.Tag;
12. import org.springframework.http.ResponseEntity;
13. import org.springframework.security.access.prepost.PreAuthorize;
14. import org.springframework.web.bind.annotation.*;
16. import java.util.Arrays;
17. import java.util.List;
19. @SecurityScheme(
20.     name = "bearerAuth",
21.     type = SecuritySchemeType.HTTP,
22.     scheme = "bearer",
23.     bearerFormat = "JWT",
24.     in = SecuritySchemeIn.HEADER,
25.     description = "JWT认证"
26. )
27. @Tag(name = "系统管理", description = "系统管理相关的API操作")
28. @RestController
29. @RequestMapping("/api/admin")
30. @SecurityRequirement(name = "bearerAuth")
31. public class AdminController {
33.     @Operation(
34.         summary = "获取系统配置",
35.         description = "获取系统全局配置信息，仅管理员可访问"
36.     )
37.     @ApiResponses(value = {
38.         @ApiResponse(responseCode = "200", description = "成功获取系统配置",
39.             content = { @Content(mediaType = "application/json",
40.                 schema = @Schema(implementation = SystemConfig.class)) }),
41.         @ApiResponse(responseCode = "403", description = "权限不足",
42.             content = @Content)
43.     })
44.     @PreAuthorize("hasRole('ADMIN')")
45.     @GetMapping("/config")
46.     public ResponseEntity<SystemConfig> getSystemConfig() {
47.         // 模拟获取系统配置
48.         SystemConfig config = new SystemConfig(
49.             "My Application",
50.             "1.0.0",
51.             Arrays.asList("en", "zh", "ja"),
52.             true,
53.             100
54.         );
55.         return ResponseEntity.ok(config);
56.     }
58.     @Operation(
59.         summary = "更新系统配置",
60.         description = "更新系统全局配置信息，仅管理员可访问"
61.     )
62.     @ApiResponses(value = {
63.         @ApiResponse(responseCode = "200", description = "成功更新系统配置",
64.             content = { @Content(mediaType = "application/json",
65.                 schema = @Schema(implementation = SystemConfig.class)) }),
66.         @ApiResponse(responseCode = "400", description = "请求参数不正确",
67.             content = @Content),
68.         @ApiResponse(responseCode = "403", description = "权限不足",
69.             content = @Content)
70.     })
71.     @PreAuthorize("hasRole('ADMIN')")
72.     @PutMapping("/config")
73.     public ResponseEntity<SystemConfig> updateSystemConfig(
74.         @Parameter(description = "系统配置信息", required = true)
75.         @Valid @RequestBody SystemConfigUpdateRequest configRequest) {
76.         
77.         // 模拟更新系统配置
78.         SystemConfig updatedConfig = new SystemConfig(
79.             configRequest.getAppName(),
80.             configRequest.getVersion(),
81.             configRequest.getSupportedLanguages(),
82.             configRequest.isMaintenanceMode(),
83.             configRequest.getMaxUploadSize()
84.         );
85.         return ResponseEntity.ok(updatedConfig);
86.     }
88.     @Operation(
89.         summary = "获取用户列表",
90.         description = "分页获取系统所有用户，管理员可访问"
91.     )
92.     @ApiResponses(value = {
93.         @ApiResponse(responseCode = "200", description = "成功获取用户列表",
94.             content = { @Content(mediaType = "application/json",
95.                 schema = @Schema(implementation = PageResult.class)) }),
96.         @ApiResponse(responseCode = "403", description = "权限不足",
97.             content = @Content)
98.     })
99.     @PreAuthorize("hasRole('ADMIN')")
100.     @GetMapping("/users")
101.     public ResponseEntity<PageResult<User>> getUsers(
102.         @Parameter(description = "页码", required = false, example = "1")
103.         @RequestParam(defaultValue = "1") int page,
104.         
105.         @Parameter(description = "每页大小", required = false, example = "10")
106.         @RequestParam(defaultValue = "10") int size,
107.         
108.         @Parameter(description = "角色过滤", required = false, example = "USER")
109.         @RequestParam(required = false) UserRole role) {
110.         
111.         // 模拟获取用户列表
112.         List<User> users = Arrays.asList(
113.             new User(1L, "admin", "admin@example.com", UserRole.ADMIN),
114.             new User(2L, "user1", "user1@example.com", UserRole.USER),
115.             new User(3L, "user2", "user2@example.com", UserRole.USER)
116.         );
117.         
118.         PageResult<User> result = new PageResult<>(
119.             users,
120.             page,
121.             size,
122.             users.size(),
123.             (int) Math.ceil((double) users.size() / size),
124.             page < Math.ceil((double) users.size() / size),
125.             page > 1
126.         );
127.         
128.         return ResponseEntity.ok(result);
129.     }
131.     @Operation(
132.         summary = "更新用户角色",
133.         description = "更新指定用户的角色，仅管理员可访问"
134.     )
135.     @ApiResponses(value = {
136.         @ApiResponse(responseCode = "200", description = "成功更新用户角色",
137.             content = { @Content(mediaType = "application/json",
138.                 schema = @Schema(implementation = User.class)) }),
139.         @ApiResponse(responseCode = "404", description = "用户不存在",
140.             content = @Content),
141.         @ApiResponse(responseCode = "403", description = "权限不足",
142.             content = @Content)
143.     })
144.     @PreAuthorize("hasRole('ADMIN')")
145.     @PutMapping("/users/{userId}/role")
146.     public ResponseEntity<User> updateUserRole(
147.         @Parameter(description = "用户ID", required = true, example = "1")
148.         @PathVariable Long userId,
149.         
150.         @Parameter(description = "用户角色", required = true, example = "ADMIN")
151.         @RequestParam UserRole role) {
152.         
153.         // 模拟更新用户角色
154.         User updatedUser = new User(userId, "user", "user@example.com", role);
155.         return ResponseEntity.ok(updatedUser);
156.     }
157. }
159. // 系统配置模型
160. @Schema(description = "系统配置")
161. class SystemConfig {
162.    
163.     @Schema(description = "应用名称", example = "My Application", requiredMode = Schema.RequiredMode.REQUIRED)
164.     private String appName;
165.    
166.     @Schema(description = "应用版本", example = "1.0.0", requiredMode = Schema.RequiredMode.REQUIRED)
167.     private String version;
168.    
169.     @Schema(description = "支持的语言列表", requiredMode = Schema.RequiredMode.REQUIRED)
170.     private List<String> supportedLanguages;
171.    
172.     @Schema(description = "是否处于维护模式", example = "false", requiredMode = Schema.RequiredMode.REQUIRED)
173.     private boolean maintenanceMode;
174.    
175.     @Schema(description = "最大上传大小（MB）", example = "100", requiredMode = Schema.RequiredMode.REQUIRED)
176.     private int maxUploadSize;
177.    
178.     public SystemConfig(String appName, String version, List<String> supportedLanguages,
179.                        boolean maintenanceMode, int maxUploadSize) {
180.         this.appName = appName;
181.         this.version = version;
182.         this.supportedLanguages = supportedLanguages;
183.         this.maintenanceMode = maintenanceMode;
184.         this.maxUploadSize = maxUploadSize;
185.     }
186.    
187.     // getters and setters
188. }
190. // 系统配置更新请求模型
191. @Schema(description = "系统配置更新请求")
192. class SystemConfigUpdateRequest {
193.    
194.     @Schema(description = "应用名称", example = "My Application", requiredMode = Schema.RequiredMode.NOT_REQUIRED)
195.     private String appName;
196.    
197.     @Schema(description = "应用版本", example = "1.0.0", requiredMode = Schema.RequiredMode.NOT_REQUIRED)
198.     private String version;
199.    
200.     @Schema(description = "支持的语言列表", requiredMode = Schema.RequiredMode.NOT_REQUIRED)
201.     private List<String> supportedLanguages;
202.    
203.     @Schema(description = "是否处于维护模式", example = "false", requiredMode = Schema.RequiredMode.NOT_REQUIRED)
204.     private Boolean maintenanceMode;
205.    
206.     @Schema(description = "最大上传大小（MB）", example = "100", requiredMode = Schema.RequiredMode.NOT_REQUIRED)
207.     private Integer maxUploadSize;
208.    
209.     // getters and setters
210. }
212. // 用户模型（简化版）
213. @Schema(description = "用户信息")
214. class User {
215.    
216.     @Schema(description = "用户ID", example = "1", requiredMode = Schema.RequiredMode.REQUIRED)
217.     private Long id;
218.    
219.     @Schema(description = "用户名", example = "john_doe", requiredMode = Schema.RequiredMode.REQUIRED)
220.     private String username;
221.    
222.     @Schema(description = "电子邮箱", example = "john.doe@example.com", requiredMode = Schema.RequiredMode.REQUIRED)
223.     private String email;
224.    
225.     @Schema(description = "用户角色", example = "USER", requiredMode = Schema.RequiredMode.REQUIRED)
226.     private UserRole role;
227.    
228.     public User(Long id, String username, String email, UserRole role) {
229.         this.id = id;
230.         this.username = username;
231.         this.email = email;
232.         this.role = role;
233.     }
234.    
235.     // getters and setters
236. }

复制代码

高级技巧与最佳实践

1. 分组管理API

在大型项目中，API数量可能很多，合理分组管理API非常重要。可以使用@Tag注解对API进行分组。

2. // 用户管理API组
3. @Tag(name = "用户管理", description = "用户相关的API操作")
4. @RestController
5. @RequestMapping("/api/users")
6. public class UserController {
7.     // ...
8. }
10. // 产品管理API组
11. @Tag(name = "产品管理", description = "产品相关的API操作")
12. @RestController
13. @RequestMapping("/api/products")
14. public class ProductController {
15.     // ...
16. }
18. // 订单管理API组
19. @Tag(name = "订单管理", description = "订单相关的API操作")
20. @RestController
21. @RequestMapping("/api/orders")
22. public class OrderController {
23.     // ...
24. }

复制代码

2. 自定义响应模型

有时API的响应模型比较复杂，可以使用@Schema注解自定义响应模型。

2. @Schema(description = "API通用响应")
3. public class ApiResponse<T> {
4.    
5.     @Schema(description = "响应码", example = "200", requiredMode = Schema.RequiredMode.REQUIRED)
6.     private int code;
7.    
8.     @Schema(description = "响应消息", example = "操作成功", requiredMode = Schema.RequiredMode.REQUIRED)
9.     private String message;
10.    
11.     @Schema(description = "响应数据", requiredMode = Schema.RequiredMode.NOT_REQUIRED)
12.     private T data;
13.    
14.     @Schema(description = "时间戳", example = "2023-01-01T12:00:00Z", requiredMode = Schema.RequiredMode.REQUIRED)
15.     private LocalDateTime timestamp;
16.    
17.     public ApiResponse(int code, String message, T data) {
18.         this.code = code;
19.         this.message = message;
20.         this.data = data;
21.         this.timestamp = LocalDateTime.now();
22.     }
23.    
24.     // getters and setters
25. }

复制代码

然后在控制器中使用：

2. @Operation(
3.     summary = "获取用户",
4.     description = "根据用户ID获取用户详细信息"
5. )
6. @ApiResponses(value = {
7.     @ApiResponse(responseCode = "200", description = "成功获取用户信息",
8.         content = { @Content(mediaType = "application/json",
9.             schema = @Schema(implementation = ApiResponse.class)) }),
10.     @ApiResponse(responseCode = "404", description = "用户不存在",
11.         content = @Content)
12. })
13. @GetMapping("/{id}")
14. public ResponseEntity<ApiResponse<User>> getUserById(@PathVariable Long id) {
15.     User user = userService.getUserById(id);
16.     ApiResponse<User> response = new ApiResponse<>(200, "成功获取用户信息", user);
17.     return ResponseEntity.ok(response);
18. }

复制代码

3. 使用枚举限制参数值

对于某些参数，其值只能是预定义的几个选项，可以使用枚举来限制。

2. @Schema(description = "排序方式")
3. public enum SortOrder {
4.     @Schema(description = "升序")
5.     ASC,
6.    
7.     @Schema(description = "降序")
8.     DESC
9. }

复制代码

然后在控制器中使用：

2. @GetMapping("/users")
3. public ResponseEntity<List<User>> getUsers(
4.     @Parameter(description = "排序字段", required = false, example = "createdAt")
5.     @RequestParam(required = false) String sortBy,
6.    
7.     @Parameter(description = "排序方式", required = false, example = "DESC")
8.     @RequestParam(required = false) SortOrder sortOrder) {
9.    
10.     List<User> users = userService.getUsers(sortBy, sortOrder);
11.     return ResponseEntity.ok(users);
12. }

复制代码

4. 使用@Hidden隐藏API

某些内部API或测试API不希望在Swagger UI中显示，可以使用@Hidden注解隐藏它们。

2. import io.swagger.v3.oas.annotations.Hidden;
4. @Hidden
5. @GetMapping("/internal/health-check")
6. public ResponseEntity<String> healthCheck() {
7.     return ResponseEntity.ok("OK");
8. }

复制代码

5. 使用@ExternalDocs添加外部文档

对于复杂的API，可能需要额外的文档说明，可以使用@ExternalDocs注解添加外部文档链接。

2. import io.swagger.v3.oas.annotations.ExternalDocumentation;
3. import io.swagger.v3.oas.annotations.extensions.Extension;
4. import io.swagger.v3.oas.annotations.extensions.ExtensionProperty;
6. @Tag(
7.     name = "支付管理",
8.     description = "支付相关的API操作",
9.     externalDocs = @ExternalDocumentation(
10.         description = "支付集成文档",
11.         url = "https://example.com/docs/payment-integration"
12.     )
13. )
14. @RestController
15. @RequestMapping("/api/payments")
16. public class PaymentController {
17.     // ...
18. }

复制代码

6. 使用@Extension添加自定义扩展

Swagger支持通过@Extension注解添加自定义扩展，这些扩展可以用于添加额外的元数据。

2. @Operation(
3.     summary = "处理支付",
4.     description = "处理用户支付请求",
5.     extensions = {
6.         @Extension(
7.             name = "x-rate-limit",
8.             properties = {
9.                 @ExtensionProperty(name = "requests", value = "100"),
10.                 @ExtensionProperty(name = "period", value = "1h")
11.             }
12.         ),
13.         @Extension(
14.             name = "x-cost",
15.             properties = {
16.                 @ExtensionProperty(name = "credits", value = "5")
17.             }
18.         )
19.     }
20. )
21. @PostMapping("/process")
22. public ResponseEntity<PaymentResult> processPayment(@Valid @RequestBody PaymentRequest request) {
23.     // ...
24. }

复制代码

常见问题与解决方案

1. Swagger UI无法访问

问题：添加Swagger依赖后，访问/swagger-ui.html返回404错误。

解决方案：

1. 确认是否正确添加了依赖：<dependency>
   <groupId>org.springdoc</groupId>
   <artifactId>springdoc-openapi-ui</artifactId>
   <version>1.6.14</version>
</dependency>
2. 对于Spring Boot 3.x，需要使用SpringDoc 2.x版本：<dependency>
   <groupId>org.springdoc</groupId>
   <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
   <version>2.1.0</version>
</dependency>
3. 确认应用程序的主类上有@SpringBootApplication注解。
4. 尝试访问不同的路径：SpringDoc 1.x:/swagger-ui.htmlSpringDoc 2.x:/swagger-ui/index.html
5. SpringDoc 1.x:/swagger-ui.html
6. SpringDoc 2.x:/swagger-ui/index.html

确认是否正确添加了依赖：

2. <dependency>
3.    <groupId>org.springdoc</groupId>
4.    <artifactId>springdoc-openapi-ui</artifactId>
5.    <version>1.6.14</version>
6. </dependency>

复制代码

对于Spring Boot 3.x，需要使用SpringDoc 2.x版本：

2. <dependency>
3.    <groupId>org.springdoc</groupId>
4.    <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
5.    <version>2.1.0</version>
6. </dependency>

复制代码

确认应用程序的主类上有@SpringBootApplication注解。

尝试访问不同的路径：

• SpringDoc 1.x:/swagger-ui.html
• SpringDoc 2.x:/swagger-ui/index.html

2. 控制器方法未显示在Swagger UI中

问题：某些控制器方法没有在Swagger UI中显示。

解决方案：

1. 确认控制器类上有@RestController或@Controller注解。
2. 确认方法上有HTTP映射注解，如@GetMapping、@PostMapping等。
3. 检查是否使用了@Hidden注解，该注解会隐藏API。
4.

2. 如果使用了Spring Security，确保已配置允许访问Swagger相关的路径：@Configuration
3. @EnableWebSecurity
4. public class SecurityConfig extends WebSecurityConfigurerAdapter {
6.    @Override
7.    protected void configure(HttpSecurity http) throws Exception {
8.        http.authorizeRequests()
9.            .antMatchers("/swagger-ui/**", "/v3/api-docs/**").permitAll()
10.            .anyRequest().authenticated();
11.    }
12. }

复制代码

确认控制器类上有@RestController或@Controller注解。

确认方法上有HTTP映射注解，如@GetMapping、@PostMapping等。

检查是否使用了@Hidden注解，该注解会隐藏API。

如果使用了Spring Security，确保已配置允许访问Swagger相关的路径：

2. @Configuration
3. @EnableWebSecurity
4. public class SecurityConfig extends WebSecurityConfigurerAdapter {
6.    @Override
7.    protected void configure(HttpSecurity http) throws Exception {
8.        http.authorizeRequests()
9.            .antMatchers("/swagger-ui/**", "/v3/api-docs/**").permitAll()
10.            .anyRequest().authenticated();
11.    }
12. }

复制代码

3. 请求/响应模型显示不正确

问题：Swagger UI中显示的请求/响应模型与实际不符。

解决方案：

1. 确保模型类上有@Schema注解，并且属性上也有相应的@Schema注解。
2.

2. 对于泛型类型，使用@ArraySchema注解：@ArraySchema(schema = @Schema(implementation = User.class))
3. private List<User> users;

复制代码

3.

2. 对于复杂的继承关系，可以使用@Schema(allOf = {...})注解：@Schema(allOf = {BaseEntity.class, User.class})
3. public class User extends BaseEntity {
4.    // ...
5. }

复制代码

4. 如果使用了@JsonIgnore或@JsonProperty等Jackson注解，确保它们与Swagger注解不冲突。

确保模型类上有@Schema注解，并且属性上也有相应的@Schema注解。

对于泛型类型，使用@ArraySchema注解：

2. @ArraySchema(schema = @Schema(implementation = User.class))
3. private List<User> users;

复制代码

对于复杂的继承关系，可以使用@Schema(allOf = {...})注解：

2. @Schema(allOf = {BaseEntity.class, User.class})
3. public class User extends BaseEntity {
4.    // ...
5. }

复制代码

如果使用了@JsonIgnore或@JsonProperty等Jackson注解，确保它们与Swagger注解不冲突。

4. 文件上传API显示不正确

问题：文件上传API在Swagger UI中显示不正确或无法测试。

解决方案：

1.

2. 确保使用了正确的请求映射和消费类型：@PostMapping(value = "/upload", consumes = MediaType.MULTIPART_FORM_DATA_VALUE)
3. public ResponseEntity<FileUploadResult> uploadFile(
4.    @RequestParam("file") MultipartFile file) {
5.    // ...
6. }

复制代码

2. 确保参数类型是MultipartFile，并且使用了@RequestParam注解。
3.

2. 对于多个文件上传，使用数组或集合类型：@PostMapping(value = "/batch-upload", consumes = MediaType.MULTIPART_FORM_DATA_VALUE)
3. public ResponseEntity<List<FileUploadResult>> batchUploadFiles(
4.    @RequestParam("files") MultipartFile[] files) {
5.    // ...
6. }

复制代码

确保使用了正确的请求映射和消费类型：

2. @PostMapping(value = "/upload", consumes = MediaType.MULTIPART_FORM_DATA_VALUE)
3. public ResponseEntity<FileUploadResult> uploadFile(
4.    @RequestParam("file") MultipartFile file) {
5.    // ...
6. }

复制代码

确保参数类型是MultipartFile，并且使用了@RequestParam注解。

对于多个文件上传，使用数组或集合类型：

2. @PostMapping(value = "/batch-upload", consumes = MediaType.MULTIPART_FORM_DATA_VALUE)
3. public ResponseEntity<List<FileUploadResult>> batchUploadFiles(
4.    @RequestParam("files") MultipartFile[] files) {
5.    // ...
6. }

复制代码

5. 认证信息无法正确传递

问题：在Swagger UI中测试需要认证的API时，认证信息无法正确传递。

解决方案：

1.

2. 确保已定义安全方案：@SecurityScheme(
3.    name = "bearerAuth",
4.    type = SecuritySchemeType.HTTP,
5.    scheme = "bearer",
6.    bearerFormat = "JWT"
7. )
8. @SpringBootApplication
9. public class MyApp {
10.    // ...
11. }

复制代码

2.

2. 在需要认证的API上添加@SecurityRequirement注解：@SecurityRequirement(name = "bearerAuth")
3. @GetMapping("/protected")
4. public ResponseEntity<String> getProtectedResource() {
5.    // ...
6. }

复制代码

3. 在Swagger UI中，点击右上角的”Authorize”按钮，输入认证信息。
4.

2. 如果使用的是API密钥认证，确保正确配置了@SecurityScheme：@SecurityScheme(
3.    name = "apiKey",
4.    type = SecuritySchemeType.APIKEY,
5.    in = SecuritySchemeIn.HEADER,
6.    paramName = "X-API-KEY"
7. )

复制代码

确保已定义安全方案：

2. @SecurityScheme(
3.    name = "bearerAuth",
4.    type = SecuritySchemeType.HTTP,
5.    scheme = "bearer",
6.    bearerFormat = "JWT"
7. )
8. @SpringBootApplication
9. public class MyApp {
10.    // ...
11. }

复制代码

在需要认证的API上添加@SecurityRequirement注解：

2. @SecurityRequirement(name = "bearerAuth")
3. @GetMapping("/protected")
4. public ResponseEntity<String> getProtectedResource() {
5.    // ...
6. }

复制代码

在Swagger UI中，点击右上角的”Authorize”按钮，输入认证信息。

如果使用的是API密钥认证，确保正确配置了@SecurityScheme：

2. @SecurityScheme(
3.    name = "apiKey",
4.    type = SecuritySchemeType.APIKEY,
5.    in = SecuritySchemeIn.HEADER,
6.    paramName = "X-API-KEY"
7. )

复制代码

总结

Swagger是一个强大的API文档工具，通过注解的方式，我们可以直接在代码中描述API，自动生成交互式文档。本文详细介绍了Swagger的常用注解，包括类级别、方法级别、参数级别和模型级别的注解，并通过实际应用场景展示了如何使用这些注解。

通过合理使用Swagger注解，我们可以：

1. 提高API文档的准确性和可维护性
2. 提供交互式API文档，方便前端开发和测试
3. 减少手动编写文档的工作量
4. 促进团队协作和沟通

在实际项目中，建议遵循以下最佳实践：

1. 为API合理分组，使用@Tag注解
2. 为每个API提供清晰的描述和示例
3. 详细描述请求参数和响应模型
4. 对于需要认证的API，正确配置安全方案
5. 定期更新文档，保持与代码同步

希望本文能帮助你深入理解Swagger注解的使用，提升API开发能力。在实际应用中，不断探索和实践，你会发现Swagger的更多强大功能。