基于 Spring Boot 3 与 OpenAPI 的微服务 API 契约测试与文档自动化闭环实践

[ Controller/DTO 代码 + Validation 注解 ]
                 │ (编译期/打包期)
                 ▼
[ springdoc-openapi-maven-plugin 抽取 openapi.json ]
                 │ (CI Pipeline)
        ┌────────┴────────┐
        ▼                 ▼
[ Spectral 规范审查 ]   [ oasdiff 破坏性变更校验 (阻断合并) ]
        │
        ▼ (校验通过)
[ 契约制品库 (Artifactory / Git) ]
        ├──────────────────────────┐
        ▼                          ▼
[ Prism 自动启动 Mock 服务 ]   [ openapi-generator 生成 WebClient SDK ]

package com.example.order.controller;

import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.media.Content;
import io.swagger.v3.oas.annotations.media.Schema;
import io.swagger.v3.oas.annotations.responses.ApiResponse;
import io.swagger.v3.oas.annotations.tags.Tag;
import jakarta.validation.Valid;
import jakarta.validation.constraints.NotBlank;
import jakarta.validation.constraints.NotNull;
import jakarta.validation.constraints.Positive;
import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.*;

@Tag(name = "订单履约接口", description = "提供订单创建与状态流转能力")
@RestController
@RequestMapping("/api/v1/orders")
public class OrderController {

    @Operation(summary = "创建订单", description = "根据传入的商品明细与用户信息创建履约单")
    @ApiResponse(responseCode = "201", description = "订单创建成功")
    @ApiResponse(responseCode = "400", description = "参数校验失败", content = @Content(schema = @Schema(hidden = true)))
    @PostMapping
    public ResponseEntity<OrderResponse> createOrder(@Valid @RequestBody CreateOrderRequest request) {
        // 业务逻辑略
        return ResponseEntity.status(HttpStatus.CREATED)
                .body(new OrderResponse("ORD_20240501_001", "CREATED"));
    }

    public record CreateOrderRequest(
            @Schema(description = "用户唯一标识", example = "USR_9527")
            @NotBlank(message = "userId 不能为空")
            String userId,

            @Schema(description = "商品 SKU 编号", example = "SKU_APPLE_15_PRO")
            @NotBlank(message = "skuId 不能为空")
            String skuId,

            @Schema(description = "购买数量", example = "1", minimum = "1")
            @NotNull(message = "quantity 不能为空")
            @Positive(message = "quantity 必须大于 0")
            Integer quantity
    ) {}

    public record OrderResponse(
            @Schema(description = "订单号", example = "ORD_20240501_001")
            String orderId,

            @Schema(description = "订单状态", example = "CREATED")
            String status
    ) {}
}

<plugin>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-maven-plugin</artifactId>
    <executions>
        <execution>
            <id>pre-integration-test</id>
            <goals>
                <goal>start</goal>
            </goals>
        </execution>
        <execution>
            <id>post-integration-test</id>
            <goals>
                <goal>stop</goal>
            </goals>
        </execution>
    </executions>
</plugin>

<plugin>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-maven-plugin</artifactId>
    <version>1.4</version>
    <executions>
        <execution>
            <id>integration-test</id>
            <goals>
                <goal>generate</goal>
            </goals>
        </execution>
    </executions>
    <configuration>
        <apiDocsUrl>http://localhost:8080/v3/api-docs</apiDocsUrl>
        <outputFileName>openapi.json</outputFileName>
        <outputDir>${project.build.directory}/contract</outputDir>
    </configuration>
</plugin>

# CI 执行命令
spectral lint target/contract/openapi.json --ruleset .spectral.yaml --fail-severity=error

# 拉取主干最新契约文件 main-openapi.json
oasdiff breaking main-openapi.json target/contract/openapi.json --fail-on ERR