SpringDoc基础应用全方位解读

文章标题：

SpringDoc基础应用深度剖析

文章内容：

SpringDoc是一款基于Spring Boot的现代化API文档生成工具，它能够通过自动扫描代码以及相关注解，生成符合OpenAPI 3.0+规范的交互式文档，并且还集成了Swagger UI来提供可视化的测试界面。下面是对它的核心内容进行详细解读：

核心特性与长处

• 即装即用
  只需添加相应依赖，无需进行复杂的配置就能自动生成文档，支持Spring WebMvc、WebFlux、Spring Security以及Jakarta EE等。
• 注解驱动
  运用JSR - 303规范的注解（像@Tag、@Operation）来替代SpringFox专属的注解，降低了学习的难度。
• 动态兼容性
  很好地适配Spring Boot 2.6+以及3.x版本（包含JDK 17+），解决了SpringFox因停止维护而产生的不兼容问题。
• 多格式输出
  支持JSON、YAML、HTML格式的文档输出，还提供分组功能，可以按照模块对接口进行划分（例如公开API和内部API）。

集成与配置

• 依赖引入（Spring Boot 3.x）

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

• 基础配置（application.yml）

springdoc:
  swagger-ui:
    # 开启swagger-ui文档展示
    enabled: true
    # UI访问路径
    path: /swagger-ui.html
    # 标签排序方式
    tags-sorter: alpha
    # 操作排序方式
    operations-sorter: alpha
    # 保持认证状态
    persistAuthorization: true
    # 禁用示例接口
    disable-swagger-default-url: true
  api-docs:
    # 开启OpenAPI展示
    enabled: true
    # OpenAPI JSON路径
    path: /v3/api-docs
  default-consumes-media-type: application/json
  default-produces-media-type: application/json
  cache:
    # 关闭文档缓存
    disabled: false
  # 显示actuator端点
  show-actuator: false
  # 推荐保持默认，显示结构化参数
  # default-flat-param-object: true
  # 允许在文档中展示Spring MVC的ModelAndView返回类型
  model-and-view-allowed: true
  # 推荐关闭以确保文档精确性
  override-with-generic-response: false

• 全局信息配置类（可选）

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

注解使用

常用注解

提示：

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

控制层注解使用示例

@RestController
@RequestMapping("/api/users")
@Tag(name = "用户管理", description = "用户相关操作API")
public class UserController{

    @Operation(summary = "获取用户信息", description = "通过用户id获取用户信息")
    @Parameters({
        @Parameter(in = ParameterIn.PATH, name = "id", description = "用户uid", required = true)
    })
    @ApiResponse(responseCode = "404", description = "User not found")
    @GetMapping("/{id}")
    public ResponseEntity<User> getUserById(@PathVariable Long id){
        // 实现代码
        return new ResponseEntity(new User(10001,"feng","ADMIN"), HttpStatusCode.valueOf(200));
    }

    @Operation(summary = "获取用户列表-分页")
    @GetMapping("/userPage.do")
    public BizResponse getUserPage(@ParameterObject UserPageForm form) {
        return BizResponse.ok(userServer.getUserPage(form));
    }

    @Operation(summary = "文件上传")
    @PostMapping(name = "/upload", consumes = MediaType.MULTIPART_FORM_DATA_VALUE)
    public BizResponse<FileInfoVo> fileUpload(
            @Parameter(description = "文件",
                    content = @Content(mediaType = MediaType.MULTIPART_FORM_DATA_VALUE,
                            schema = @Schema(type = "string", format = "binary")))
            @RequestParam MultipartFile file) {
        FileInfo fileInfo = fileStorageService.of(file).setPath(uploadFilePath).upload();
        return BizResponse.ok(fileInfo);
    }
}

模型注解使用示例

import io.swagger.v3.oas.annotations.media.Schema;
import io.swagger.v3.oas.annotations.media.Schema.RequiredMode;
import jakarta.validation.constraints.Email;
import jakarta.validation.constraints.Size;

@data
public class User{

    @Schema(description = "用户ID", example = "1001")
    private Integer id;

    @Schema(description = "用户名", example = "john_doe", requiredMode = RequiredMode.REQUIRED)
    @Size(min = 3, max = 20, message = "用户名长度必须在3到20个字符之间")
    private String username;

    @Schema(description = "用户角色", allowableValues = {"ADMIN", "USER", "GUEST"})
    private String role;

    @Schema(description = "邮箱", example = "john_doe@mail.com")
    @Email
    private String email;

    @Schema(description = "最近登录时间", example = "2025-07-15 12:25:32", type = "string")
    private Date lastLoginTime;

    @Schema(description = "出生年月日", example = "2025-07-15", type = "string")
    @JsonFormat(pattern = "yyyy-MM-dd", timezone = "GMT+8")
    private Date birthDate;
}

文件上传注解使用示例

• 文件上传必须声明以下配置，否则SpringDoc无法识别为文件类型，文件参数不会显示为文件上传控件
  • @PostMapping必须配置consumes = MediaType.MULTIPART_FORM_DATA_VALUE
  • MultipartFile参数必须明确声明format = "binary"
• 单文件上传

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

• 多文件上传（数组形式）

@Parameter(
    description = "多文件上传",
    content = @Content(
        mediaType = MediaType.MULTIPART_FORM_DATA_VALUE,
        array = @ArraySchema( // 声明数组类型
            schema = @Schema(type = "string", format = "binary")
        )
    )
)
@RequestParam("files") MultipartFile[] files

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

@RequestBody(
    description = "混合参数请求",
    content = @Content(
        mediaType = MediaType.MULTIPART_FORM_DATA_VALUE,
        encoding = {
            @Encoding(name = "file", contentType = "image/jpeg"), // 指定文件类型
            @Encoding(name = "remark", contentType = "text/plain") // 文本参数
        }
    )
)
@RequestPart("file") MultipartFile file,
@RequestPart("remark") String remark

分组与扩展功能

分组配置

• 按模块隔离接口

@Bean
public GroupedOpenApi publicApi() {
    return GroupedOpenApi.builder()
        .group("公开接口")
        .pathsToMatch("/api/public/**")
        .build();
}

@Bean
public GroupedOpenApi adminApi() {
    return GroupedOpenApi.builder()
        .group("管理接口")
        .pathsToMatch("/api/admin/**")
        .addOpenApiMethodFilter(method -> method.isAnnotationPresent(PreAuthorize.class))
        .build();
}

访问Swagger UI右上角可切换分组

生产环境安全建议

• 通过配置动态关闭文档

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

从SpringFox迁移指南

迁移优势：
* 支持Spring Boot 3.x和JDK 17+；
* 注解更简洁，符合OpenAPI 3规范

最佳实践与常见问题

1. 依赖冲突
   排除旧版Swagger依赖（如springfox-swagger2），避免与SpringDoc冲突1。
2. 拦截器导致文档无法访问
   若项目使用Spring Security，需放行文档路径：

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

1. 文档生成失败排查
   检查控制器是否被扫描：确保@RestController位于springdoc.packages-to-scan指定路径下

总结

SpringDoc凭借零配置启动、注解简洁以及深度兼容Spring生态的优势，已经成为Spring Boot API文档的首选工具。它的核心价值在于：
* 自动化——减少手动维护文档的成本；
* 标准化——严格遵循OpenAPI 3规范；
* 可扩展——分组、安全控制灵活适配复杂项目。
访问http://localhost:8080/swagger-ui.html即可查看交互式文档（默认路径）