摘要
本月,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,我会尽快回复您。
我渴望让我们的受众拥有出色的以用户为中心的文件,并希望您加入我们,共同实现这一愿景。