SpringDoc 基本使用指南

SpringDoc 是基于 Spring Boot 的现代化 API [成]q=%E6%96%87%E6%A1%A3%E7%94%9F%E6%88%90&spm=1001.2101.3001.7020)工具,通过自动化扫描代码和注解,生成符合 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)

    xml 复制代码
    <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>
    
    AI写代码xml
    12345
  • 基础配置(application.yml)

    yaml 复制代码
    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
    
    AI写代码yaml
    1234567891011121314151617181920212223242526272829303132
  • 全局信息配置类(可选)

    less 复制代码
    @Configuration
    @OpenAPIDefinition(
      info = @Info(title = "项目API文档", version = "1.0", description = "SpringBoot接口文档")
    )
    public class SpringDocConfig { 
      // 无需额外代码
    }
    
    AI写代码java
    运行
    1234567

注解使用

常用注解

场景 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 注解,自动在文档中标记权限需求。

控制层注解使用示例

less 复制代码
@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);
    }
}

AI写代码java
运行
123456789101112131415161718192021222324252627282930313233

模型注解使用示例

less 复制代码
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 clas sUser{

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

AI写代码java
运行
1234567891011121314151617181920212223242526272829

文件上传注解使用示例

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

    • @PostMapping 必须配置 consumes = MediaType.MULTIPART_FORM_DATA_VALUE
    • MultipartFile 参数必须明确声明 format = "binary"
  • 单文件上传

    less 复制代码
    @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) {
        // 业务逻辑
    }
    
    AI写代码java
    运行
    1234567891011121314
  • 多文件上传(数组形式)

    less 复制代码
    @Parameter(
        description = "多文件上传",
        content = @Content(
            mediaType = MediaType.MULTIPART_FORM_DATA_VALUE,
            array = @ArraySchema( // 声明数组类型
                schema = @Schema(type = "string", format = "binary")
            )
        )
    )
    @RequestParam("files") MultipartFile[] files
    
    AI写代码java
    运行
    12345678910
  • 混合参数(文件+表单数据)

    less 复制代码
    @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
    
    AI写代码java
    运行
    123456789101112

分组与扩展功能

分组配置

  • 按模块隔离接口

    csharp 复制代码
    @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();
    }
    
    AI写代码java
    运行
    12345678910111213141516

    访问 Swagger UI 右上角切换分组

生产环境安全建议

  • 通过配置动态关闭文档

    yaml 复制代码
    springdoc:
      swagger-ui:
        enabled: false   # 生产环境禁用 UI
      api-docs:
        enabled: false   # 禁用 OpenAPI 端点:cite[1]
    
    AI写代码yaml
    12345

从 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 依赖(如 springfox-swagger2),避免与 SpringDoc 冲突1。

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

    若项目使用 Spring Security,需放行文档路径:

    scss 复制代码
    http.authorizeRequests().antMatchers("/swagger-ui/**", "/v3/api-docs/**").permitAll();
    
    AI写代码java
    运行
    1
  3. 文档生成失败排查

    检查控制器是否被扫描:确保 @RestController 位于 springdoc.packages-to-scan 指定路径下

总结

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

  • 自动化 - 减少手动维护文档的成本;
  • 标准化 - 严格遵循 OpenAPI 3 规范;
  • 可扩展 - 分组、安全控制灵活适配复杂项目。
  • 访问 http://localhost:8080/swagger-ui.html 即可查看交互式文档(默认路径)
相关推荐
杨DaB2 小时前
【SpringMVC】拦截器,实现小型登录验证
java·开发语言·后端·servlet·mvc
小宋10217 小时前
多线程向设备发送数据
java·spring·多线程
鹦鹉0078 小时前
SpringMVC的基本使用
java·spring·html·jsp
努力的小雨8 小时前
还在为调试提示词头疼?一个案例教你轻松上手!
后端
魔都吴所谓9 小时前
【go】语言的匿名变量如何定义与使用
开发语言·后端·golang
陈佬昔没带相机9 小时前
围观前后端对接的 TypeScript 最佳实践,我们缺什么?
前端·后端·api
Livingbody11 小时前
大模型微调数据集加载和分析
后端
Livingbody11 小时前
第一次免费使用A800显卡80GB显存微调Ernie大模型
后端
橘子编程11 小时前
SpringMVC核心原理与实战指南
java·spring boot·spring·tomcat·mybatis
Goboy12 小时前
Java 使用 FileOutputStream 写 Excel 文件不落盘?
后端·面试·架构