标准答案
- OpenAPI、Protobuf 或其他契约可明确路径、方法、字段类型、必填性、错误响应、认证方式和示例，为前后端与第三方建立同一语言。
- 契约可以驱动客户端 SDK、服务端校验、Mock、文档站、兼容性检查和契约测试，降低手工复制字段说明造成的偏差。
- 人工文档更适合解释业务语义、接入步骤、迁移背景、限额和常见错误，但其中的字段定义应链接或引用可验证契约。
- 契约变更应进入代码评审和 CI，检测破坏性字段变更、未更新示例和服务实现与声明不一致的问题。
- 契约本身也要有 owner、版本、发布流程和真实调用验证；写了 YAML 不代表生产行为已经正确。
题目解析
协作成本往往来自多份真相：Controller、前端类型、SDK、Postman 集合、Wiki 和网关配置各自维护。契约能收敛结构性事实。
复杂业务规则不能只靠 schema 表达，仍需要清晰的错误码、示例、测试数据和边界说明。
常见误区
- 把接口文档当作发布后才补的静态截图。
- 生成 SDK 后就不再做兼容测试和真实联调。
- 只维护人工文档，字段、枚举和错误码长期与实现不一致。