OpenAPI Contract First 落到工程里要定的事：工具栈如何拼、AI 怎么起草 spec、团队同步机制、breaking change 治理、常见坑的对策，以及老项目的迁移路径。

API 与 event contract 的兼容性保障按问答拆开：BFF 对外用 oasdiff 守 OpenAPI spec，内部 BFF 到 MS、MS 到 MS 用 JSON Schema 快照补 japicmp 的盲区，Kafka 事件再加 per-event schemaVersion。

BFF 与微服务之间到底该共享到哪一步？Shop Platform 的 monorepo 实践之外，共享 contracts、共享 client 和契约测试在 polyrepo 下各有 tradeoff，我目前更倾向其中一种组合。

在 Gateway + BFF + Domain Service 架构下，记录一种用 Spring Cloud Gateway MVC 和 SpringDoc 聚合 OpenAPI 文档的做法，方便前后端协作和接口自查。

介绍 OpenAPI 3.1 相比 3.0 的几项核心变化：JSON Schema 2020-12 对齐、nullable 语义重构、webhooks 原生支持，以及我在项目里做升级验证时看到的收益与边界。