Pulumi Cloud REST API 文档，现由 OpenAPI 生成
Source: Pulumi Blog
为什么这很重要
之前的 REST API 参考文档是一套手写页面。每新增一个端点、重命名参数或修改响应结构，都需要相应的文档 PR，实际操作中这些页面往往会出现漂移。小的细节不一致会累积成大问题：缺失参数、过时的请求结构，以及与 API 实际返回不匹配的模式。我们需要一种持久的解决方案，使文档能够在 API 迭代时保持同步。
从 OpenAPI 规范生成参考文档可以弥补这一缺口。当 API 有变更时，文档会在下次构建时自动更新。
新增内容
/docs/reference/cloud-rest-api/ 处的参考文档现在包括：
- 更快找到所需信息 – 按产品领域（Stacks、Deployments、Environments、Organizations、Registry、Insights、AI、Workflows 等）对端点进行分组，便于直接跳转到正在使用的 API 部分。
- 完整的请求与响应细节 – 每个端点都记录其参数、请求体以及返回的精确结构，让你无需猜测即可知道该发送什么、期待收到什么。
- 一键在相关类型之间导航 – 当响应引用其他对象时，类型名称会成为链接。点击即可深入查看完整定义，而不必在冗长的 API 参考页面中滚动查找。
为代理（Agent）解锁的可能性
让参考文档与规范保持同步不仅是对人类的便利，更改变了 AI 代理读取文档并代表你调用 API 的可靠性。手写参考文档可能仍显示六个月前被重命名的参数，或遗漏 API 现在返回的字段，导致调用静默失败或难以调试。当参考文档直接由规范生成时，代理使用的正是 API 当前实际接受的内容。
想象一下，你正在为新团队在 Pulumi Cloud 中开通权限。只需让代理阅读 REST API 参考文档并指示它：
- 创建一个
sre‑oncall团队。 - 添加四名成员。
- 为三个 stack 授予管理员权限。
代理会遍历团队、成员关系和 stack 权限的端点，构建正确的调用顺序并执行。
相同的模式同样适用于批量审计和清理。让代理查找组织中所有近期未更新的 stack 并标记为 stale；它能够正确分页，因为响应模式与实际相符。虽然之前这些工作流在技术上是可能的，但现在可靠性大幅提升。
同一 URL，现有链接仍可使用
生成的文档仍位于之前的 URL：/docs/reference/cloud-rest-api/。书签、博客链接以及外部搜索流量仍会指向正确页面。对于已被修改、重命名或移动的任何 API 参考页面，系统已设置重定向。
试一试
从全新的 REST API 参考文档 开始，按分类浏览。每个页面都会链接到其使用的请求和响应对象模式。
如果你发现任何错误，最可能的原因是 OpenAPI 规范本身——请在 pulumi/docs 中提交 issue，我们会追溯到源头。对于标签引入和结构改进，欢迎向 pulumi/docs 提交 PR。问题和反馈可随时在 Pulumi Community Slack 中提出。