API 文档生成工具——SpringDoc

一、与Swagger的关系

时间线:

  • 2010 年,Wordnik 的 Tony Tam 做了 Swagger,用来描述 REST API;
  • Swagger 2.0 规范加上 Swagger UI / Editor / Codegen 工具链,成为事实标准;
  • 2015 年 Swagger 规范捐给 Linux 基金会,2016 年改名为 OpenAPI Specification (OAS),2017 年 OAS 3.0 发布------从此 OpenAPI 是规范,Swagger 是工具品牌;
  • SpringFox 曾是 Spring 生态最流行的实现,但 2020 年 3.0.0 之后基本停更:Spring Boot 2.6 默认路径匹配策略切到 PathPatternParser 后大面积启动报错,Spring Boot 3(Jakarta EE 9)直接不兼容;
  • SpringDoc 接棒:运行时扫描 Spring 配置、类结构和注解,自动生成 OpenAPI 3 文档(JSON/YAML),并内置 Swagger UI 渲染。

总结:OpenAPI 是"文档的格式标准",Swagger UI 是"看文档的界面",SpringDoc 是"自动生成文档的引擎" 。 @Operation 注解来自 io.swagger.v3.oas.annotations(Swagger 的注解库),文档格式是 OpenAPI 3,渲染界面是 Swagger UI------三者协作,各司其职。

二、SpringDoc 的特色

  1. 零配置 :加依赖就有文档,默认 /v3/api-docs(JSON)、/v3/api-docs.yaml、/swagger-ui.html;
  2. 注解 + JSR-303 联动 :@NotNull、@Min、@Max、@Size 自动映射为 Schema 约束,前端看到的校验规则和后端真实校验一致;
  3. 分组多文档 :GroupedOpenApi 按包/路径拆出 admin、open 等多份文档;
  4. 全栈支持:WebMVC / WebFlux 双栈、Kotlin、GraalVM Native Image;3.x 还支持 Scalar UI 和 MCP(AI 工具调用那套协议);
  5. 扩展点丰富 :OpenApiCustomizer / OperationCustomizer 全局改文档,OAuth2 / JWT 安全方案一行代码接入;
  6. 社区活跃:非 Pivotal 官方维护,但迭代节奏跟得上 Spring Boot 大版本。

版本矩阵:

Spring Boot SpringDoc 依赖坐标
1.x / 2.x 1.8.x springdoc-openapi-ui
3.x 2.10.x springdoc-openapi-starter-webmvc-ui
4.x 3.2.x springdoc-openapi-starter-webmvc-ui(Java 17+)

从 2.8.7 起官方提供 BOM(springdoc-openapi-bom),多模块项目建议用它统一管理版本。

三、快速上手(Spring Boot 4 + SpringDoc 3.2)

第一步:引依赖

xml 复制代码
<dependencyManagement>
  <dependencies>
    <!-- BOM 统一管理 springdoc 版本,子模块不用重复写 version -->
    <dependency>
      <groupId>org.springdoc</groupId>
      <artifactId>springdoc-openapi-bom</artifactId>
      <version>3.2.0</version>
      <type>pom</type>
      <scope>import</scope>
    </dependency>
  </dependencies>
</dependencyManagement>

<dependencies>
  <!-- WebMVC + 内置 Swagger UI;只要 JSON 不要 UI 时改用 starter-webmvc-api -->
  <dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
  </dependency>
</dependencies>

第二步:基础配置

yaml 复制代码
springdoc:
  api-docs:
    path: /v3/api-docs          # OpenAPI JSON 地址
  swagger-ui:
    path: /swagger-ui.html      # UI 地址
    operations-sorter: method   # 按 HTTP 方法排序,方便阅读
  packages-to-scan: com.example.demo.controller  # 只扫业务包,避免 actuator 混进文档

第三步:给 Controller 加注解

java 复制代码
package com.example.demo.controller;

import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.Parameter;
import io.swagger.v3.oas.annotations.media.Schema;
import io.swagger.v3.oas.annotations.tags.Tag;
import jakarta.validation.Valid;
import jakarta.validation.constraints.Max;
import jakarta.validation.constraints.Min;
import jakarta.validation.constraints.NotBlank;
import org.springframework.web.bind.annotation.*;

import java.util.List;

@Tag(name = "用户接口", description = "用户注册、查询相关接口")  // 对应 UI 左侧分组
@RestController
@RequestMapping("/api/users")
public class UserController {

    /** @Operation 描述接口,@Parameter 描述查询参数;JSR-303 约束自动进文档 */
    @Operation(summary = "分页查询用户", description = "按页返回用户列表,page 从 1 开始")
    @GetMapping
    public List<String> list(
            @Parameter(description = "页码") @RequestParam(defaultValue = "1") @Min(1) int page,
            @Parameter(description = "每页条数,最大 100") @RequestParam(defaultValue = "10") @Max(100) int size) {
        return List.of("user-" + page + "-" + size);
    }

    /** @Valid 让 JSR-303 校验生效;请求体字段约束会体现在 Schema 中 */
    @Operation(summary = "创建用户")
    @PostMapping
    public String create(@Valid @RequestBody CreateUserReq req) {
        return "created: " + req.name();
    }

    /** 请求体模型:@Schema 描述字段,与 JSR-303 注解共同构成文档 */
    public record CreateUserReq(
            @Schema(description = "用户名", example = "tom") @NotBlank String name,
            @Schema(description = "年龄", example = "18") @Min(0) @Max(150) Integer age) {
    }
}

第四步:配置文档元信息 + JWT 鉴权 + 分组

java 复制代码
package com.example.demo.config;

import io.swagger.v3.oas.models.Components;
import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.info.Info;
import io.swagger.v3.oas.models.security.SecurityRequirement;
import io.swagger.v3.oas.models.security.SecurityScheme;
import org.springdoc.core.models.GroupedOpenApi;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class OpenApiConfig {

    /** 全局文档信息 + JWT 方案:UI 右上角会出现 Authorize 按钮 */
    @Bean
    public OpenAPI demoOpenAPI() {
        String scheme = "BearerAuth";
        return new OpenAPI()
                .info(new Info().title("Demo 服务 API").version("v1.0.0")
                        .description("SpringDoc 3.2 + Spring Boot 4 示例"))
                // 声明 Bearer Token 鉴权方案
                .components(new Components().addSecuritySchemes(scheme,
                        new SecurityScheme().type(SecurityScheme.Type.HTTP)
                                .scheme("bearer").bearerFormat("JWT")))
                // 全局应用该方案,单个接口也可用 @SecurityRequirement 覆盖
                .addSecurityItem(new SecurityRequirement().addList(scheme));
    }

    /** 分组文档:/v3/api-docs/admin 只包含 /api/admin/** 的接口 */
    @Bean
    public GroupedOpenApi adminApi() {
        return GroupedOpenApi.builder()
                .group("admin")
                .pathsToMatch("/api/admin/**")
                .build();
    }
}

启动后访问 http://localhost:8080/swagger-ui.html 即可;OpenAPI JSON 在 /v3/api-docs,分组文档在 /v3/api-docs/admin。

四、生产场景:网关聚合与文档即代码

场景 1:微服务网关聚合文档。 每个服务各自暴露 /v3/api-docs,网关侧(WebFlux 栈用 springdoc-openapi-starter-webflux-ui)用 Swagger UI 的 urls 配置统一入口,下拉切换:

yaml 复制代码
# 网关服务配置
springdoc:
  swagger-ui:
    urls:
      - name: 用户服务
        url: /user-service/v3/api-docs   # 网关路由转发到用户服务
      - name: 订单服务
        url: /order-service/v3/api-docs

配合网关路由的 RewritePath 把 /user-service/** 转发到后端服务,文档和真实接口走同一套路由,不会出现"文档地址对不上"的问题。

场景 2:文档即代码(CI 导出 + SDK 生成)。 在流水线里把 openapi.json 导出为构建产物,交给 openapi-generator 生成前端 TypeScript SDK / Java Client------接口一改,SDK 自动更新,接口文档从"附件"变成"契约":

yaml 复制代码
# CI 步骤示例:应用启动后抓取 OpenAPI 契约文件
- name: Export OpenAPI spec
  run: |
    mvn -q spring-boot:run -Dspring-boot.run.profiles=ci &   # 后台启动应用
    sleep 20
    curl -sf http://localhost:8080/v3/api-docs -o openapi.json  # 抓取契约
    kill %1                                                   # 关闭应用

也可以改用 springdoc-openapi-maven-plugin,在 integration-test 阶段自动启动应用并抓取文档,产物默认写到 target/openapi.json,适合和 openapi-generator-maven-plugin 串在一条构建链上。

五、踩坑

  1. 版本错配:Boot 3 配 springdoc 1.x 会因 javax/jakarta 冲突起不来;Boot 4 必须用 3.x;
  2. springfox 残留 :老项目升级时务必删干净 springfox-* 依赖,两套注解/扫描器共存会导致文档重复、Tag 混乱;
  3. 生产暴露风险 :文档页会暴露全部接口结构,生产环境建议 springdoc.api-docs.enabled=false 且 springdoc.swagger-ui.enabled=false,或把文档挂到网关鉴权之后;
  4. Security 放行 :Spring Security 下要放行 /v3/api-docs/**、/swagger-ui/**、/swagger-ui.html,否则 UI 白屏;
  5. 扫描范围 :用 packages-to-scan 限定业务包,避免 actuator、错误页混进文档;
  6. 泛型/循环引用 :复杂泛型返回会生成晦涩的 Schema 名,必要时用 @Schema(name = "...") 显式命名。

六、总结

  • Swagger 是工具品牌,OpenAPI 是规范,SpringDoc 是 Spring 生态的文档生成引擎;
  • SpringFox 已停更,SpringDoc 是 Boot 3/4 时代的事实标准;
  • 用对版本(Boot 4 → 3.2.x)、加好注解、配好分组和鉴权,文档就从"负担"变成"契约":网关聚合统一入口,CI 导出生成 SDK,接口变更自动进流水线。
相关推荐
这个昵称不容易1 小时前
SpringBoot 医疗病历交互系统毕设:192 个 Java 文件、256 个接口、22 张表,附真实运行截图
java·springboot·毕设
Pniubi11 小时前
怎么排查慢SQL,怎么解决?
java·数据库·sql
薛之谦_12 小时前
Java 全栈知识体系:从 IDEA 高效开发到 JVM、并发与 Stream 实战
java·jvm·intellij-idea
文丑颜不良啊16 小时前
LeetCode2761~2780题目解析
java·leetcode
IT枫斗者枫哥16 小时前
子线程断言失败,JUnit 为什么还显示通过?
java·后端
考虑考虑18 小时前
JDK27中的Set.ofLazy
java·后端·java ee
文丑颜不良啊19 小时前
LeetCode2841~2860题目解析
java·leetcode
小南家的青蛙19 小时前
Tomcat与Jetty深度对比
java·tomcat·jetty
乌暮20 小时前
Spring AOP 与 Spring 事务:用大白话彻底理解原理与实践
java·数据库·spring boot·后端·sql·学习·spring