SpringDoc基本使用的方法示例

宗清莹

SpringDoc 是基于 Spring Boot 的现代化 API 文档生成工具，通过自动化扫描代码和注解，生成符合 OpenAPI 3.0+ 规范 的交互式文档，并集成 Swagger UI 提供可视化测试界面。以下是其核心详解：

核心特性与优势

• 开箱即用

  仅需添加依赖，无需复杂配置即可自动生成文档，支持 Spring WebMvc、WebFlux、Spring Security 及 Jakarta EE。

• 注解驱动

  使用 JSR-303 规范注解（如

  1. @Tag

  复制代码
  、
  1. @Operation

  复制代码
  ）替代 SpringFox 专属注解，降低学习成本。

• 动态兼容性

  完美适配 Spring Boot 2.6+ 及 3.x（含 JDK 17+），解决 SpringFox 因停维护导致的不兼容问题。

• 多格式输出

  支持 JSON/YAML/HTML 格式文档，并提供分组功能，可按模块划分接口（如公开 API 与内部 API）。

集成与配置

依赖引入（Spring Boot 3.x）

1. <dependency>
2. <groupId>org.springdoc</groupId>
3. <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
4. <version>2.5.0</version> <!-- 官方稳定版，兼容 Spring Boot 3.3.x:cite[2]:cite[8] -->
5. </dependency>

复制代码

基础配置（application.yml）

1. springdoc:
2. swagger-ui:
3. # 开启 swagger-ui 文档展示
4. enabled: true
5. # UI访问路径
6. path: /swagger-ui.html
7. # 标签排序方式
8. tags-sorter: alpha
9. # 操作排序方式
10. operations-sorter: alpha
11. # 保持认证状态
12. persistAuthorization: true
13. # 禁用示例接口
14. disable-swagger-default-url: true
15. api-docs:
16. # 开启 OpenAPI 展示
17. enabled: true
18. # OpenAPI JSON路径
19. path: /v3/api-docs
20. default-consumes-media-type: application/json
21. default-produces-media-type: application/json
22. cache:
23. # 关闭文档缓存
24. disabled: false
25. # 显示actuator端点
26. show-actuator: false
27. # 推荐保持默认，显示结构化参数
28. # default-flat-param-object: true
29. # 允许在文档中展示 Spring MVC 的 ModelAndView 返回类型
30. model-and-view-allowed: true
31. # 推荐关闭以确保文档精确性
32. override-with-generic-response: false

复制代码

全局信息配置类（可选）

1. @Configuration
2. @OpenAPIDefinition(
3. info = @Info(title = "项目API文档", version = "1.0", description = "SpringBoot接口文档")
4. )
5. public class SpringDocConfig {
6. // 无需额外代码
7. }

复制代码

注解使用

常用注解

场景	SpringDoc 注解	示例
控制器描述	@Tag(name="模块", description="")	@Tag(name="用户管理", description="用户CRUD")
接口方法描述	@Operation(summary="", description="")	@Operation(summary="创建用户", description="需管理员权限")
参数描述	@Parameter(description="")	@Parameter(description="用户ID", required=true)
模型属性描述	@Schema(description="")	public class User { @Schema(description="用户名") private String name; }l
解析对象属性为查询参数	@ParameterObject	public BizResponse getUserPage(@ParameterObject UserPageForm form) {}

提示：

• @Hidden 可隐藏接口或参数；
• 支持 Spring Security 的 @PreAuthorize 注解，自动在文档中标记权限需求。

控制层注解使用示例

1. @RestController
2. @RequestMapping("/api/users")
3. @Tag(name = "用户管理", description = "用户相关操作API")
4. public class UserController{
6. @Operation(summary = "获取用户信息", description = "通过用户id获取用户信息")
7. @Parameters({
8. @Parameter(in = ParameterIn.PATH, name = "id", description = "用户uid", required = true)
9. })
10. @ApiResponse(responseCode = "404", description = "User not found")
11. @GetMapping("/{id}")
12. public ResponseEntity<User> getUserById(@PathVariable Long id){
13. // 实现代码
14. return new ResponseEntity(new User(10001,"feng","ADMIN"), HttpStatusCode.valueOf(200));
15. }
17. @Operation(summary = "获取用户列表-分页")
18. @GetMapping("/userPage.do")
19. public BizResponse getUserPage(@ParameterObject UserPageForm form) {
20. return BizResponse.ok(userServer.getUserPage(form));
21. }
23. @Operation(summary = "文件上传")
24. @PostMapping(name = "/upload", consumes = MediaType.MULTIPART_FORM_DATA_VALUE)
25. public BizResponse<FileInfoVo> fileUpload(
26. @Parameter(description = "文件",
27. content = @Content(mediaType = MediaType.MULTIPART_FORM_DATA_VALUE,
28. schema = @Schema(type = "string", format = "binary")))
29. @RequestParam MultipartFile file) {
30. FileInfo fileInfo = fileStorageService.of(file).setPath(uploadFilePath).upload();
31. return BizResponse.ok(fileInfo);
32. }
33. }

复制代码

模型注解使用示例

1. import io.swagger.v3.oas.annotations.media.Schema;
2. import io.swagger.v3.oas.annotations.media.Schema.RequiredMode;
3. import jakarta.validation.constraints.Email;
4. import jakarta.validation.constraints.Size;
6. @data
7. public clas sUser{
9. @Schema(description = "用户ID", example = "1001")
10. private Integer id;
12. @Schema(description = "用户名", example = "john_doe", requiredMode = RequiredMode.REQUIRED)
13. @Size(min = 3, max = 20, message = "用户名长度必须在3到20个字符之间")
14. private String username;
16. @Schema(description = "用户角色", allowableValues = {"ADMIN", "USER", "GUEST"})
17. private String role;
19. @Schema(description = "邮箱", example = "john_doe@mail.com")
20. @Email
21. private String email;
23. @Schema(description = "最近登录时间", example = "2025-07-15 12:25:32", type = "string")
24. private Date lastLoginTime;
26. @Schema(description = "出生年月日", example = "2025-07-15", type = "string")
27. @JsonFormat(pattern = "yyyy-MM-dd", timezone = "GMT+8")
28. private Date birthDate;
29. }

复制代码

文件上传注解使用示例

文件上传必须声明以下配置，否则 SpringDoc 无法识别为文件类型，文件参数不会显示为文件上传控件

• 1. @PostMapping

  复制代码
  必须配置
  1. consumes = MediaType.MULTIPART_FORM_DATA_VALUE

  复制代码
• 1. MultipartFile

  复制代码
  参数必须明确声明
  1. format = "binary"

  复制代码

单文件上传

1. @PostMapping(value = "/upload", consumes = MediaType.MULTIPART_FORM_DATA_VALUE)
2. @Operation(summary = "上传文件")
3. public ResponseEntity<String> uploadFile(
4. @Parameter(
5. description = "文件参数",
6. required = true,
7. content = @Content( // 关键：嵌套Content注解
8. mediaType = MediaType.APPLICATION_OCTET_STREAM_VALUE,
9. schema = @Schema(type = "string", format = "binary") // 明确格式
10. )
11. )
12. @RequestParam("file") MultipartFile file) {
13. // 业务逻辑
14. }

复制代码

多文件上传（数组形式）

1. @Parameter(
2. description = "多文件上传",
3. content = @Content(
4. mediaType = MediaType.MULTIPART_FORM_DATA_VALUE,
5. array = @ArraySchema( // 声明数组类型
6. schema = @Schema(type = "string", format = "binary")
7. )
8. )
9. )
10. @RequestParam("files") MultipartFile[] files

复制代码

混合参数（文件+表单数据）

1. @RequestBody(
2. description = "混合参数请求",
3. content = @Content(
4. mediaType = MediaType.MULTIPART_FORM_DATA_VALUE,
5. encoding = {
6. @Encoding(name = "file", contentType = "image/jpeg"), // 指定文件类型
7. @Encoding(name = "remark", contentType = "text/plain") // 文本参数
8. }
9. )
10. )
11. @RequestPart("file") MultipartFile file,
12. @RequestPart("remark") String remark

复制代码

分组与扩展功能

分组配置

按模块隔离接口

1. @Bean
2. public GroupedOpenApi publicApi() {
3. return GroupedOpenApi.builder()
4. .group("公开接口")
5. .pathsToMatch("/api/public/**")
6. .build();
7. }
9. @Bean
10. public GroupedOpenApi adminApi() {
11. return GroupedOpenApi.builder()
12. .group("管理接口")
13. .pathsToMatch("/api/admin/**")
14. .addOpenApiMethodFilter(method -> method.isAnnotationPresent(PreAuthorize.class))
15. .build();
16. }

复制代码

访问 Swagger UI 右上角切换分组

生产环境安全建议

通过配置动态关闭文档

1. springdoc:
2. swagger-ui:
3. enabled: false # 生产环境禁用 UI
4. api-docs:
5. enabled: false # 禁用 OpenAPI 端点:cite[1]

复制代码

从 SpringFox 迁移指南

SpringFox 注解	SpringDoc 替代方案
@Api	@Tag
@ApiOperation	@Operation(summary="", description="")
@ApiModelProperty	@Schema(description="")
@ApiParam	@Parameter
@ApiIgnore	@Hidden

迁移优势：

• 支持 Spring Boot 3.x 和 JDK 17+；
• 注解更简洁，符合 OpenAPI 3 规范

最佳实践与常见问题

1. 依赖冲突

   排除旧版 Swagger 依赖（如

   1. springfox-swagger2

   复制代码
   ），避免与 SpringDoc 冲突1。

2. 拦截器导致文档无法访问

   若项目使用 Spring Security，需放行文档路径：

   1. http.authorizeRequests().antMatchers("/swagger-ui/**", "/v3/api-docs/**").permitAll();

   复制代码

3. 文档生成失败排查

   检查控制器是否被扫描：确保

   1. @RestController

   复制代码
   位于
   1. springdoc.packages-to-scan

   复制代码
   指定路径下

总结

SpringDoc 凭借 零配置启动、注解简洁 和 深度兼容 Spring 生态 的优势，已成为 Spring Boot API 文档的首选工具。其核心价值在于：

• 自动化 - 减少手动维护文档的成本；
• 标准化 - 严格遵循 OpenAPI 3 规范；
• 可扩展 - 分组、安全控制灵活适配复杂项目。
• 访问
  1. http://localhost:8080/swagger-ui.html

  复制代码
  即可查看交互式文档（默认路径）

到此这篇关于SpringDoc基本使用的方法示例的文章就介绍到这了,更多相关SpringDoc使用内容请搜索晓枫资讯以前的文章或继续浏览下面的相关文章希望大家以后多多支持晓枫资讯！ 

免责声明：如果侵犯了您的权益，请联系站长，我们会及时删除侵权内容，谢谢合作！

悠然802L

感谢楼主，顶。