OpenAPI 是什么

OpenAPI 用一份结构化文件描述 HTTP 接口的路径、参数、请求与响应模式，是接口协作的通用载体。它可以生成文档、客户端 SDK、服务端骨架与测试用例，让接口契约从口头约定与聊天记录，变成可以被工具读取和校验的产物。

怎么避免文档与实现两张皮

把规范文件当成契约而不是文档附件：接入契约测试或在网关做请求响应校验，让实现与规范不一致时构建直接失败。设计上建议先写规范再写实现，这样接口形态由业务需求决定，而不是被实现细节裹挟着反向变形。

最小片段

openapi: 3.1.0
info:
  title: Orders API
  version: 1.0.0
paths:
  /orders/{id}:
    get:
      parameters:
        - name: id          # 路径参数必须标记必需
          in: path
          required: true
          schema: { type: string }
      responses:
        '200': { description: 订单详情 }
        '404': { description: 订单不存在 }
        '429': { description: 触发限流 }

编写要点

• 模式里明确标记必填与可空，避免生成代码把可选字段当成必需
• 为响应定义明确的错误结构与状态码，不要只写成功分支
• 枚举值增加时消费方要能容忍未知值，避免破坏兼容
• 复用组件定义，减少分散重复的模式
• 为每个操作写明鉴权要求与限流口径

基本信息

怎么落到工程里

常见做法是把规范文件放进代码仓库并与接口代码同源管理：服务端用规范生成骨架或校验请求，客户端用规范生成 SDK，测试用例也从规范推导。提交时校验规范格式与兼容性，若新增必填字段或删除已有字段就阻断合并，契约演进才有强制力。