接口文档规范：Swagger/OpenAPI 3.0规范、接口文档自动化生成、接口变更管理

接口文档这件事，说实话，很多团队都吃过亏。我见过最夸张的项目，文档和代码完全是两个世界——前端按文档联调，后端按代码跑，结果三天联不通一个登录接口。后来我定了一条铁律：文档必须从代码生成，不能手写。今天我们就聊聊怎么把这条铁律落地。

为什么非要用 OpenAPI 3.0？

OpenAPI 3.0 是接口描述的行业标准。它比 Swagger 2.0 更严谨，支持复用、组合、多态。我个人习惯直接用 OpenAPI 3.0 规范写 YAML，而不是 Swagger 2.0。原因很简单：3.0 的 oneOf、anyOf 能精准描述复杂响应，这在微服务场景下太常用了。

接口文档自动化生成

手动维护文档？别想了。我建议直接用注解 + 工具链自动生成。下面是我在 Spring Boot 项目里的标准配置。

1. 引入依赖

<!-- SpringDoc OpenAPI 3.0 -->
<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
    <version>2.3.0</version>
</dependency>

2. 配置 OpenAPI 信息

@Configuration
public class OpenApiConfig {
    @Bean
    public OpenAPI customOpenAPI() {
        return new OpenAPI()
            .info(new Info()
                .title("订单服务 API")
                .version("2.0.0")
                .description("订单核心链路接口，包含创建、支付、退款"))
            .addSecurityItem(new SecurityRequirement()
                .addList("bearerAuth"))
            .components(new Components()
                .addSecuritySchemes("bearerAuth",
                    new SecurityScheme()
                        .type(SecurityScheme.Type.HTTP)
                        .scheme("bearer")
                        .bearerFormat("JWT")));
    }
}

3. 注解驱动文档

嗯，这里要注意：注解不是越多越好。我一般只加三个：@Operation、@ApiResponse、@Schema。够用，不冗余。

@RestController
@RequestMapping("/api/orders")
@Tag(name = "订单管理", description = "订单 CRUD 及状态流转")
public class OrderController {

    @Operation(summary = "创建订单", description = "提交商品列表生成订单，返回订单号")
    @ApiResponse(responseCode = "201", description = "创建成功",
        content = @Content(schema = @Schema(implementation = OrderResponse.class)))
    @ApiResponse(responseCode = "400", description = "参数校验失败")
    @PostMapping
    public ResponseEntity<OrderResponse> createOrder(
            @RequestBody @Valid CreateOrderRequest request) {
        // 业务逻辑
        return ResponseEntity.status(201).body(orderService.create(request));
    }
}

接口变更管理

接口变了，文档没变——这是最常见的线上事故源头。我曾经因为一个字段类型从 Integer 改成 Long，前端没收到通知，线上直接报类型转换异常。从那以后，我强制团队做三件事。

变更管理三板斧

自动化差异对比脚本

# 在 CI 中执行
openapi-diff --old docs/v1/openapi.yaml --new docs/v2/openapi.yaml \
  --output-format markdown > diff-report.md

# 如果检测到 breaking change，直接让流水线失败
if grep -q "breaking" diff-report.md; then
  echo "检测到破坏性变更，请通知所有消费者！"
  exit 1
fi

知识体系总览

下面这张图概括了接口文档规范的核心链路。我每次给团队培训都会先画一遍。

落地检查清单

最后，给你一份我每次项目启动都会过的检查清单。照着做，文档问题能减少 80%。

• 规范选型：是否统一使用 OpenAPI 3.0？有没有混用 Swagger 2.0？
• 自动生成：文档是否从代码注解自动生成？有没有人手动改 YAML？
• 版本策略：URL 是否带版本号？旧版本是否保留兼容？
• 变更通知：CI 中是否集成了 openapi-diff？破坏性变更是否阻断流水线？
• 消费者契约：前端/客户端是否基于生成的文档做 Mock？有没有契约测试？