自动生成 API 开发文档

TCC 模式（Try-Confirm-Cancel)

在供应链金融的 [仓单质押] 场景中，TCC 模式（Try-Confirm-Cancel）是保障分布式事务一致性的核心方案。它通过拆分业务为三个阶段，解决跨系统（如仓单系统、融资系统、风控系统）操作的原子性问题，避免仓单被重复质押、质押状态不一致等风险。

在 Spring Boot 项目中，最常用的自动生成 API 开发文档的方式是通过 Swagger/OpenAPI 工具，其中目前推荐使用 SpringDoc OpenAPI（基于 OpenAPI 3.0 规范，是 Swagger 的升级版，对 Spring Boot 支持更友好）。

步骤 1：添加 SpringDoc 依赖

在pom.xml中添加以下依赖（根据 Spring Boot 版本选择对应版本，以 Spring Boot 3.x 为例）：

xml

<!-- SpringDoc OpenAPI 核心依赖 -->
<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
    <version>2.1.0</version>
</dependency>

如果是 Spring Boot 2.x，依赖版本使用1.6.15左右，并调整 groupId 为org.springdoc:springdoc-openapi-ui。

步骤 2：配置 OpenAPI 文档信息

创建配置类，自定义 API 文档的基本信息（标题、描述、版本等）：

SpringDoc OpenAPI配置类

V1

创建时间：09:50

步骤 3：使用注解描述接口和参数

通过注解在 Controller、DTO、实体类上添加说明，让文档更清晰：

常用注解说明：

示例：在 Controller 中使用注解

带文档注解的控制器示例

V1

创建时间：09:50

示例：在 DTO 中使用注解

带文档注解的DTO示例

V1

创建时间：09:50

步骤 4：访问 API 文档

启动 Spring Boot 项目后，通过以下地址访问自动生成的文档：

1. Swagger UI 界面（可视化交互文档）：
   http://localhost:8080/api/swagger-ui.html
   （如果项目有上下文路径context-path，需要加上，例如上面配置的/api）

2. OpenAPI JSON 格式文档（供其他工具解析）：
   http://localhost:8080/api/v3/api-docs

进阶配置（可选）

1. 过滤不需要的接口：
   在配置类中排除特定路径或包，不生成文档：

   java

   运行

   @Bean
   public OpenAPI customOpenAPI() {
       return new OpenAPI()
               .info(...)
               .paths(new Paths()
                   .addPathItem("/error", new PathItem().description("忽略错误接口")));
   }
   

2. 生产环境关闭文档：
   在application-prod.properties中禁用：

   properties

   springdoc.api-docs.enabled=false
   springdoc.swagger-ui.enabled=false
   

3. 整合 Spring Security：
   如果项目有安全拦截，需要允许 Swagger 相关路径匿名访问：

   java

   运行

   @Configuration
   public class SecurityConfig {
       @Bean
       public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
           http.authorizeHttpRequests(auth -> auth
               // 允许Swagger路径匿名访问
               .requestMatchers("/swagger-ui/**", "/v3/api-docs/**").permitAll()
               .anyRequest().authenticated()
           );
           return http.build();
       }
   }
   

总结

通过 SpringDoc OpenAPI 插件，只需：

1. 添加依赖 → 2. 配置文档基本信息 → 3. 用注解描述接口和参数 → 4. 访问 Swagger UI
   即可自动生成规范化、可交互的 API 开发文档，方便前后端协作和接口测试。文档会随着代码注解的更新自动同步，无需手动维护。

本作品采用《CC 协议》，转载必须注明作者和本文链接