摘要
本月，developer.openstack.org 网站焕新，并更改了其源工具。请阅读以下内容，了解这些更改如何影响您的项目团队。
我们为什么要更改 developer.openstack.org 网站？
您可能知道，developer.openstack.org 网站记录了已经存在于 developer.openstack.org 网站上的十几个 OpenStack 服务的 900 多个 GET/PUT/POST/DELETE/PATCH 调用。正如东京峰会上几位主题演讲者优雅地指出的那样，OpenStack API 的可信度和一致性影响了他们将业务工作负载运行在 OpenStack 云上的决定。
这些接口需要文档，大量的文档，而不仅仅是参考文档。虽然维护准确的 参考 需要巨大的努力，但我们也需要记录 API 的使用方法和场景。
现在我们已经编写了 API 指南 和一个“编写您的第一个 OpenStack 应用程序”教程，我们希望该网站成为应用程序开发者、产品开发者以及任何需要释放 OpenStack 基础设施力量的人的首选地点。
在此版本中，文档平台引入了工具，可让您从 WADL 迁移到 Swagger，并将基于 RST 的文档与 API 参考文档集成。 “为什么”分析很明确：我们必须社区化这些信息，并使其易于维护和更新，以便用户能够信任它，并将其工作负载押注在它上面。
稍后，本文将回答“如何”的问题。
为什么在这个发布版本中进行所有这些更改？
好吧，我们不需要像发布服务文档那样发布 API 文档。我们对该网站进行了很多维护，包括错误修复等。但现在是时候冒险了。上一个版本我们做了一个概念验证。这个版本我们发布了一个解决方案，帮助我们朝着我们的目标取得增量进展。
1 月 16 日之后，您如何保持 API 文档的更新？
1 月 16 日，我们将 Images API WADL 和 DocBook 文件迁移到 Swagger 和 RST 文件。然后我们将测试构建过程和内容本身，以验证迁移。
测试之后，我们将迁移以下服务的的文件
- 身份验证
- 计算
- Images
- Networks
- 块存储
- Object Storage
然后，其余服务可以使用经过验证的工具迁移其文件。
如果您提供 OpenStack API 服务，请继续阅读。
对于 nova 项目，请将您的操作指南和概念性文章放在 nova 仓库的 api-guide 文件夹中。其他项目可以模仿 创建 api-guide 和 为 Compute api-guide 构建任务 这些补丁。您继续在 openstack/api-site 仓库中更新参考信息。但是，源文件已更改。
在此版本中，您可以将注释嵌入到源代码中，如果您想生成参考信息。这是 nova 项目的一个 示例补丁。由于我们还没有一个项目完全做到这一点，构建任务仍然需要编写。
如果您的项目已经有 WADL 文件，它们将被迁移到 Swagger 文件并存储在 api-site 仓库中。WADL 文件将被删除；您可以从 Git 中检索它们。
如果您的项目没有 WADL 文件，那么您需要编写 Swagger 加上 RST 来记录您的 API 调用、参数和参考信息。您可以从注释生成 Swagger，或者从头开始创建 Swagger，并将其存储在 api-site 仓库中。您应该从您的项目团队的仓库中审查、存储和构建 RST，以获取概念性或操作指南信息。
所有项目都应使用 OpenStack API 工作组的这套 API 文档指南，只要他们的服务具有 REST API。本文档告诉您应该编写什么以及如何编写。如果您遵循建议的提纲，您的 API 指南将准确而完整。
在源文件和构建任务存在之后，文档将被构建到 developer.openstack.org。
在哪里可以获得我项目 API 指南的帮助？
这些规范描述了详细信息：应用程序开发者指南 和 重做 API 参考信息。
您可以在 #openstack-sdks 或 #openstack-docs 上 IRC 上提问。我们期待那些会实现愿望的 API 文档仙女，但与此同时，我们可以为您指明方向并为您提供完成任务的工具。
如果我仍然有疑问怎么办？
通过电子邮件或 IRC 联系我，Anne Gentle，我会尽快回复您。
我渴望通过优秀的以用户为中心的文档来赋能我们的受众，并希望您加入我们，共同实现这一愿景。
发表评论