基于 Spring Boot 3 与 OpenAPI 规范的后端架构文档工程化落地实践

<properties>
    <springdoc.version>2.3.0</springdoc.version>
</properties>

<dependencies>
    <!-- 引入 WebMVC 支持与 Swagger UI -->
    <dependency>
        <groupId>org.springdoc</groupId>
        <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
        <version>${springdoc.version}</version>
    </dependency>
</dependencies>

@Tag(name = "User Management", description = "用户账户核心服务")
@RestController
@RequestMapping("/api/v1/users")
public class UserController {

    /**
     * 根据用户 ID 查询用户详情
     * 
     * @param userId 业务唯一用户 ID
     * @return 用户聚合信息
     */
    @Operation(summary = "查询用户详情", description = "若用户不存在，返回 404 状态码")
    @GetMapping("/{userId}")
    public ResponseEntity<UserResponse> getUserById(
            @PathVariable @NotBlank String userId) {
        // 业务实现省略
        return ResponseEntity.ok(new UserResponse(userId, "春豆李", UserStatus.ACTIVE));
    }
}

springdoc:
  api-docs:
    path: /v3/api-docs
    enabled: true
  swagger-ui:
    path: /swagger-ui.html
    operations-sorter: alpha
    tags-sorter: alpha
  packages-to-scan: com.example.project.controller

@startuml
!include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Container.puml

Person(customer, "终端用户", "使用移动端 App 进行下单与支付")
System_Boundary(c1, "核心交易体系") {
    Container(api_gateway, "API Gateway", "Spring Cloud Gateway", "路由、限流与鉴权")
    Container(order_service, "Order Service", "Spring Boot 3.x", "负责订单生命周期")
    Container(payment_service, "Payment Service", "Spring Boot 3.x", "处理结算、退款与第三方通道对接")
    ContainerDb(db, "Payment DB", "PostgreSQL 15", "存储支付流水与账单")
}
System_Ext(wechat_pay, "微信支付平台", "外部三方收单通道")

Rel(customer, api_gateway, "发起支付请求", "HTTPS/JSON")
Rel(api_gateway, order_service, "路由请求", "gRPC")
Rel(order_service, payment_service, "创建支付单", "gRPC")
Rel(payment_service, db, "持久化事务", "JDBC")
Rel(payment_service, wechat_pay, "调用代扣接口", "HTTPS")
@enduml

# GitHub Actions 示例片段
name: API Backward Compatibility Check

on:
  pull_request:
    paths:
      - 'src/main/java/**/controller/**'

jobs:
  check-api:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Set up JDK 17
        uses: actions/setup-java@v4
        with:
          java-version: '17'
          distribution: 'temurin'
      
      - name: Export Current OpenAPI Spec
        run: |
          mvn test-compile org.springframework.boot:spring-boot-maven-plugin:run -Dspring-boot.run.arguments="--spring.profiles.active=doc-export" &
          sleep 15
          curl http://localhost:8080/v3/api-docs > new-openapi.json

      - name: Fetch Base Branch OpenAPI Spec
        run: |
          git checkout origin/main
          # 同样方式获取 main 分支的历史基线契约 old-openapi.json (流程略)

      - name: Run OpenAPI Diff
        run: |
          docker run --rm -v $(pwd):/specs openapitools/openapi-diff:latest \
            /specs/old-openapi.json /specs/new-openapi.json \
            --fail-on-incompatible