可进入评审的 Markdown
生成结果适合放进工单、PR 或设计评审。它应在实现开始前写清责任人、决策、证据和后续工作。
Endpoint: POST /refunds 兼容性：响应增加字段 请求： - idempotency_key：必填 - order_id：必填 错误： - REFUND_ALREADY_PENDING - ORDER_NOT_REFUNDABLE
API 规格生成器
定义端点、模式和错误代码——获取即用的 API 规格。复制 Markdown、下载或导出 OpenAPI YAML。
api-spec.md
这个工具实际会产出什么
导出之后
把生成的API 契约当成起点，而不是最终答案。替换示例值，补证据，指定评审人，删掉团队不会维护的字段。
- 把输出放在实现工作旁边。
- 每条验收项都要映射到测试或评审证据。
- 不要粘贴密钥、客户数据或私有事故细节。
什么是 API 规格？
API 规格是一份结构化的契约，在编写任何实现代码之前，定义端点、请求/响应模式、认证方式和错误代码。它是前端和后端团队、第三方集成方以及自动化测试工具的唯一真相来源。
先写 API 规格再编码可以防止集成不匹配，减少团队间的沟通成本，并实现并行开发。有了清晰的契约，前端团队可以模拟端点，后端团队可以实现它们——双方都清楚预期结果。
了解更多：什么是规格优先开发？或浏览我们的API 规格模板。
如何用好这个生成器
先确定契约边界
填写字段前先写清消费者和提供方。一份有用的 API 规格应该回答谁会调用这个端点、它代表哪个业务事件、由哪个版本负责，以及未来变更需要遵守什么兼容承诺。
请求和响应示例要真实
示例应包含真实感 ID、时间戳、枚举、分页字段和错误结构。只有模式没有示例时，客户端团队仍然会猜测空值、默认值和字段命名规则。
把错误当作产品行为定义
错误响应也是契约的一部分。写清稳定错误码、重试建议、校验消息、认证失败、速率限制，以及客户端应向用户展示或向支持团队记录什么。
人工评审后再导出 OpenAPI
先用 Markdown 输出讨论行为。一旦端点行为达成一致，再导出 OpenAPI YAML，让客户端生成、模拟服务、合约测试和文档共享同一份来源。
实现前的评审问题
兼容性
端点后续新增字段会不会破坏客户端？枚举变更、必填字段、默认值和弃用策略是否已经明确？
幂等性
客户端超时后重试时，服务端会不会创建重复数据？对于写操作，要定义幂等键、重复检测和安全重试行为。
可观测性
规格是否包含关联 ID、审计事件、指标，以及足够支持排障但不会暴露敏感数据的错误细节？
弱规格和强规格对比
弱规格
POST /orders 创建订单。返回成功或错误。
这会让客户端团队继续猜测幂等性、校验失败、支付状态、部分成功以及哪些字段是稳定契约。
强规格
POST /orders 接收幂等键，付款前校验库存，对重复键返回 ORDER_ALREADY_EXISTS，并把 payment_status 暴露为 authorized 或 declined。
这给前端、后端、测试和支持团队提供了足够细节，可以按同一份契约实现和验证。
导出之后怎么落地
放进实现任务，而不是私下保存
把生成的 Markdown 链接到 ticket 或 issue 中，写清接口负责人、评审人、版本决策，以及需要提前确认的调用方。这样实现开始前，所有人看到的是同一份契约，而不是聊天记录里的零散结论。
把样例转成契约测试
请求样例、成功响应和错误响应都可以成为 CI 里的 fixture。API 规格真正完成的标志，不是复制到了文档里，而是当响应结构不兼容时，测试能在发布前失败。
第一次联调后再更新一次
真实调用方常会暴露分页、重试、字段语义或错误码不够清楚的问题。上线前把这些发现写回规格，避免最终发布的契约和团队实际集成的行为不一致。
如果这个接口会被外部客户、合作方或 AI agent 调用，建议在发布说明中同步列出稳定字段、弃用窗口和错误恢复方式，避免调用方只能从实现行为中反推契约。
内部 API 也应如此处理，因为团队变动后，未写进契约的默认行为最容易被误改。
如果接口还没有真实消费者，也可以先写预期消费者和未来兼容承诺，避免第一版过早锁死。
后续有消费者接入时，再把实际用到的字段补进契约测试。
完成后的 API 规格应该证明什么
调用方不需要猜规则
调用方应该能根据规格处理成功、校验失败、权限失败、限流、超时重试和重复提交，而不需要再向接口提供方询问隐藏约定。
提供方知道以后怎么改
规格应写清哪些变更是累加型，哪些需要版本边界，哪些需要提前通知消费者，哪些必须有迁移计划才能发布。
导出后如何进入评审
先让调用方看示例
把导出的 Markdown 连同一个成功示例和一个失败示例发给调用方。客户端团队通常能更快发现缺字段、枚举不稳定、重试行为不清晰等问题，因为示例比抽象接口描述更容易验证。
把评审问题变成契约测试
如果有人问“字段缺失时会怎样”或“这个请求能不能重试”，不要只在评论里回答。把问题写进规格，并在实现前转成 contract test，避免同一个决策散落在聊天记录里。
API 规格常见问题
应该先写 Markdown 还是 OpenAPI？
团队还在讨论行为时，先写 Markdown 更好。契约稳定到可以生成客户端、模拟服务和自动化合约测试时，再导出 OpenAPI。
备注里应该写什么？
写发布节奏、弃用计划、速率限制、跨服务依赖、安全假设和测试期望。备注区能把隐藏的集成风险提前暴露出来。
这个工具如何设计和复查
来自常见契约失败
字段围绕最容易破坏调用方的 API 决策设计：请求结构、响应结构、错误分类、幂等性、认证和兼容策略。目标是在编码前暴露集成风险。
按规格产物复查
生成结果会按 Spec Coding 的编辑标准检查：评审者应能把 Markdown 转成契约测试、实现任务和调用方交接说明，而不是依赖私下解释。
由编辑维护
作者与编辑：Daniel Marsh。复查流程：编辑政策。纠错与工具问题：联系。最近复查：2026 年 4 月 28 日。