Postman 的 Mock、Documentation 与 Spec Hub
从 examples、mock server、documentation 到 Spec Hub，理解 Postman 在 API-first 工作流中的平台能力。
#tech / dev / api
#type / synthesis
#status / growing
#resource / postman
[!info] related notes
- 所属 MOC: postman-moc, 后端开发 MOC
- 相关概念: Open API Swagger, 接口规范
- 相关资源: APIFox, msw-mock-service-worker
Postman 的 Mock、Documentation 与 Spec Hub
范围
这篇笔记讲 Postman 从“请求工具”走向 API-first 平台的那部分能力：spec、example、mock、documentation。
为什么要放在一起理解
这几项能力其实是一条连续链：
spec -> example -> mock -> documentation -> 协作消费
如果分开看，很容易把 mock 误认为只是测试辅助，把文档误认为只是导出页面。
依赖路径 / 调用链 / 演进链
1. Examples 是连接点
examples 同时服务：
- 文档展示
- mock server 响应匹配
- 测试与示例参考
2. Mock Server
它最适合的价值是：
- 前后端并行开发
- 构造异常和边界场景
- 第三方 API 不稳定时做稳定替代
3. Documentation
Postman 文档的关键优势是：
- 文档和请求资产共址
- 文档会跟着 collection / spec 更新
- 阅读者可以直接从文档进入可执行请求
4. Spec Hub
Spec Hub 更偏 API 设计与规范中心，适合：
- OpenAPI / AsyncAPI / GraphQL / gRPC 规格管理
- API-first 评审
- mock / doc / test 的上游输入
对比与易混淆点
Mock 不只是“假接口”
在 API-first 流程里，它是前后端并行和契约验证的重要中间层。
Documentation 不只是导出静态文档
它依附 collection / spec，是可执行资产的阅读视图。
Spec Hub 不等于 Swagger UI
Swagger UI 更偏单份 OpenAPI 的展示；Spec Hub 更偏组织级的规格管理和设计入口。