接口文档和实际返回对不上 字段变更怎么管

openapi: 3.0.0
paths:
  /api/list:
    get:
      responses:
        '200':
          description: OK
# 生成后与实现比对

前端按文档对接，联调时发现字段名和类型都不一样，来回沟通多次。先别急着动参数，把报错原文和时间点记下来，顺序反了容易白折腾。

原因不复杂，文档手写且没有随代码更新，缺少校验机制。

「接口文档一致性」排查到最后往往是很小的一处差异，前面那些复杂猜测可以先放一放。动手前把原文件复制一份带时间戳，出问题立刻换回去，比现场分析快得多。

一次只改一处，改完立刻验证，几个改动叠在一起，出问题就说不清是谁导致的。先做最小复现，能稳定跑出来的问题，排查成本会低一个数量级。

别只看报错的最后一行，往上看几行，真正的起因通常在上面。同类问题如果隔一段时间又出现，多半是某个定时任务或重启流程把改动冲掉了。

处理上按这个顺序：文档由代码注解生成；把文档校验加入流水线；变更时同步版本号。

改完只确认一件事：文档与实际返回完全一致，前端按文档即可完成对接。