重构 API 参考信息¶

问题描述¶

通过此蓝图，我们希望解决以下问题

• 由于工具和 REST API 知识的特殊性，API 参考信息在历史上一直难以使用社区或公司资源进行维护。
• API 参考信息需要从 API 编写者、API 开发者、贡献开发者和 API 工作组成员可以一起审查的地方获取。

此蓝图应提供我们提供上游 API 参考信息给云用户的方式的重大重构。目标受众是应用程序开发者和 SDK 开发者，他们需要关于每个服务 REST API 的精确和准确的信息。这并非内部 API 的信息，例如计算项目 (nova) 用于调度计算主机的 RPC API。这些参考用于构建具有正确请求参数的正确 API 调用，并对照您在进行调用时在屏幕上看到的结果，来双重检查您的云提供商的结果。

目前，OpenStack API Complete Reference 站点上记录了 915 个 GET/PUT/POST/DELETE/PATCH 调用，网址为 https://developer.openstack.org/api-ref.html。

目前，API 参考信息位于单独的仓库 api-site 中。在 kilo 版本（Nov14-Apr15）中，我们将所有“叙述性”信息移动到项目选择的仓库中。对于大多数项目，该位置是 <project>-spec 仓库。对于计算和对象存储，是其项目 doc/source 仓库。API 参考信息仍然在 api-site 仓库中。

随着拥有 REST API 的团队数量超过 20 个，我们需要严格执行 API 参考信息维护和构建的位置。

理想情况下，我们将使团队能够在将所有来源整合到一个易于消费、可读的各种服务 REST API 指南中时进行审查。这些应该是方便的开发者指南，提供对单独来源信息的统一视图。

现在我们已经描述了问题和简要讨论了愿景，让我们来谈谈解决方案。

提议的变更¶

我们希望确保使用当前项目的源代码来创建最准确和最新的 API 参考文档。我们还希望确保审查在最好的审查人员保持警惕的仓库中进行。

因此，作为一个概念验证，编写一个 Python 库，该库使用 Python routes 库来检查源代码并输出一个标准，例如 Swagger 版本 2，该标准可用于文档输出或请求和响应的模拟测试，以便我们最终可以构建一个连续测试层，以确保即使代码发生更改，示例的向后兼容性。

以下是设想的过程概述：#. 执行 git clone 命令以获取项目仓库的副本。 #. 使用 api-paste.ini 文件中的一些配置信息运行自动化脚本以创建 Swagger。 #. 对每个项目重复并测试。

以下是 OpenStack 项目中使用的 Web 服务器网关接口 (wsgi) 框架列表

• Ironic: pecan, wsme
• Nova: routes, JSONSchema
• Cinder: routes
• Glance: routes, JSONSchema
• Neutron: routes
• Trove: routes
• Heat: routes
• Saraha: flask
• Swift: None
• Keystone: routes
• Ceilometer: pecan
• Barbican: pecan

作为参考，这些项目已经在 openstack/api-site 仓库 中记录

• ceilometer: Telemetry 或 Telemetry 模块
• cinder: OpenStack 块存储（两个版本）
• glance: OpenStack 镜像服务（两个版本）
• heat: Orchestration 或 Orchestration 模块
• keystone: OpenStack Identity（两个版本）
• neutron: OpenStack Networking
• nova: OpenStack Compute（两个版本）
• sahara: OpenStack 数据处理服务
• swift: OpenStack 对象存储
• trove: OpenStack 数据库服务

API 文档位于其他地方或状态未知

• barbican: 密钥管理服务
• ironic: 裸机服务
• tripleo: 部署
• zaqar: 消息服务
• designate: DNS 服务
• magnum: 容器服务
• murano: 应用程序目录
• congress: 非领域特定策略执行
• rally: 基准测试服务
• mistral: 工作流服务

要求包括

编写：信息和来源必须由项目开发者维护和审查，API 工作组知情，文档团队提供支持。

编写：API 参考信息可以自动生成，字符串存储在代码中，或者可以协作编写和审查。有关更多信息，请查看下面的 标准概述。

编写：API 参考信息审查应使用 APIImpact 和 DocImpact 标志。

编写：需要一个用于编写的开源工具链。

输出：输出必须为 SDK 开发者和使用 OpenStack 云资源的应用程序开发者提供出色的体验。可选地，它将为每个调用提供一个“试用”沙箱，在 TryStack 上使用经过身份验证的凭据时。

输出：输出应指示 OpenStack 的哪个版本将支持特定的 API 版本，并在像 Compute 和 Identity 这样的可扩展 API 中，指示特定扩展与哪个版本可用。

输出：由于我们可能需要分阶段的方法来确定时间和范围，因此应与当前文档一起使用，例如使用重定向或集成显示。

构建：必须基于 Gerrit 审查和工作流程进行自动化。

范围：必须在六个月的发布周期内可行。

可选功能

构建：可选地，构建任何云提供商可以消耗并在其客户文档中重用的部分。

合同验证：可选地，提供请求和响应的验证，以验证其有效性并可以针对公共云端点工作。

更改编译：可选地，提供更改列表，以帮助审查人员发现可以修复的措辞、示例中的不一致性、参数命名、更好的人工分组的潜力等。

"personality": [
         {
            "path": "/etc/banner.txt",
            "contents": "ICAgICAgDQo...mQgQmFjaA=="
         }
      ]

注意事项¶

Russell Sim 已经为 Volume API v2 进行了概念验证。他可以上传一个示例供团队其余成员开始工作。他调查了使用 httpdomain，但似乎这需要依赖生产中的 Sphinx，激怒打包者和操作员。相反，他正在制作一个用 docutils 编写的兼容解析器。这样，我们希望以后能够重用文档来使用 Sphinx 构建，但不必将 Sphinx 作为运行时依赖项。

CORS 跨项目规范 应该有助于使用 AngularJS 显示结果，因为它是一个类似的想法。

Identity v3 在核心中具有最多的调用，为 74 个，但 Compute v2 加上扩展程序具有超过 120 个调用。

目前，创建 API 参考信息的 openstack/api-site 仓库记录了最后两个稳定版本。我们当前的策略是不合并任何 API 的 master 版本的更改，因为最终用户通常无法访问具有该更改的云。

对于此规范中的新方法，示例是基于遍历源代码生成的，因此我们的工具首先必须应用于 cinder stable/juno 并输出，例如。接下来，将工具应用于 cinder stable/kilo 分支并生成输出。为了测试目的，可以将该工具应用于 cinder master 分支，并在发生向后不兼容的更改时发出标志，或者在示例发生更改时发出标志，并注意发布说明中的更改。应按调用显示版本和微版本。

实现¶

依赖项¶

• 为了将此功能放置在 oslo 中，我们需要 oslo 评审人员的合作。
• API 工作组正在密切关注，并将帮助确保解决方案满足我们的需求。

测试¶

输出应该经过跨浏览器、跨操作系统兼容性测试。

生成 Swagger 不应需要 Sphinx 作为运行时依赖，以确保我们不会引入不需要的全局依赖。

参考资料¶

与此规范相关的先前未实现的设计蓝图

• https://blueprints.launchpad.net/openstack-manuals/+spec/autogenerate-api-reference 生成 API 参考信息和示例是一个好的前进方向。但是，我们将用这个实现规范取代这个蓝图，因为该蓝图没有相关的详细规范。
• https://blueprints.launchpad.net/openstack-manuals/+spec/api-samples-to-api-site 将内容移动到项目仓库将是相反的移动方向，并且可能非常适合此用例。
• https://blueprints.launchpad.net/openstack-manuals/+spec/api-try-it-out 我认为这应该是一个延伸目标，不一定需要实现主要目标，即改善未来的贡献和维护。

附加信息

• API 考古学：接口的复杂性和大小 http://justwriteclick.com/2015/01/12/api-archaeology-complexity-and-sizing-of-an-interface/ 这篇博文给出了 1 月发布日期时的计数。截至 2015 年 4 月 27 日，计数现在为 915 个调用。
• 具有 REST API 的服务列表：http://git.openstack.org/cgit/openstack/governance/tree/reference/projects.yaml
• WADL2Swagger 的问题：根本问题在于 Swagger 定义本身应该需要 JSON schema 才能有用和具有合同约束力。https://github.com/rackerlabs/wadl2swagger/issues/8
• 2014 年 11 月用户调查数据 http://superuser.openstack.org/articles/openstack-user-survey-insights-november-2014
• 2015 年 4 月用户调查数据（应用开发者）http://superuser.openstack.org/articles/openstack-application-developers-share-insights
• API 文档工作会议 Etherpad https://etherpad.openstack.org/p/Documentation__API_Work_Session
• Pecan 装饰器用于创建 swagger 的概念验证 https://github.com/elmiko/pecan-swagger