OpenAPI Schemas

https://blueprints.launchpad.net/cinder/+spec/openapi

我们希望开始以行业标准、机器可读的方式记录我们的 API。这样做为 OpenStack 开发人员和 OpenStack 用户都带来了许多机会，特别是能够自动生成和自动验证客户端工具和文档。在可用的许多 API 描述语言中，OpenAPI（以前称为“Swagger”）似乎是开发人员最广泛使用的一种，并且由于许多 OpenStack 服务中使用的现有工具，它最适合 OpenStack，因此我们选择使用这种格式。

问题描述

API 描述语言的历史主要是一部半成品想法、不必要的复杂性和总体失败的历史。这种历史反映在 OpenStack 尝试记录 API 的历史中，从我们早期使用 WADL 到我们对 Swagger 2.0 和 RAML 的实验，最终导致今天使用我们自定义的 os_api_ref 项目，该项目基于 reStructuredText 和 Sphinx。

只有近年来，随着 OpenAPI、RAML 和 API Blueprint 等广泛使用的 API 描述语言以及 Postman 和 Apigee 等支持 SaaS 的工具的发展，情况才开始有所稳定。特别是 OpenAPI 在多个领域得到了广泛采用，像 CloudFlare 和 GitHub 这样的站点为其 API 提供了 OpenAPI 模式。OpenAPI 近年来发展迅速，现在支持各种 API 模式，包括 Webhooks 等。更重要的是，对于 OpenStack 而言，OpenAPI 3.1 是 JSON Schema 的完全超集，这意味着我们可以重用我们已经拥有的许多验证功能。

用例

作为最终用户，我希望能够访问机器可读的、完全验证的 API 文档，这些 API 是我将与之交互的。

作为最终用户，我希望能够静态查看托管在现有文档站点上的文档，而无需运行 Cinder 的实例。

作为 SDK/客户端开发人员，我希望能够自动生成绑定和客户端，从而提高一致性并最大限度地减少开发和维护这些工具所需的体力劳动。

作为 Cinder 开发人员，我希望拥有一个经过验证的 API 规范，以便在需要替换我们使用的 Web 框架/库（如果它们不再维护）时可以使用。

提议的变更

这项工作可以分解为几个不同的步骤

  • 添加缺少的请求体和查询字符串模式

    这些模式将仅仅验证已经允许的内容，这意味着广泛使用 "additionalProperties": true 或空模式。

    一旦添加了这些模式，将添加测试以确保所有 API 资源都具有适当的模式。

  • 添加响应体模式

    这些模式将从现有的 OpenAPI 模式中获取，目前发布在 opendev.org/openstack/codegenerator 上，并从测试中生成的 JSON 响应体自动生成的新的模式中获取，并手动修改以处理枚举值等。

    一旦添加了这些模式，将添加测试以确保所有 API 资源都具有适当的响应体模式。此外，我们将添加一个新的配置选项，该选项将控制我们在 API 层进行验证的方式，[api] response_validation。这将是一个枚举值，具有三个选项

    error

    如果 API 返回“无效”响应，则引发 HTTP 500（服务器错误）。

    这将是 CI 中的默认设置，即对于我们的单元、功能和集成测试。最终这也可以成为生产环境的默认设置（但可能不会）。

    warn

    记录关于“无效”响应的警告，提示操作员针对 Cinder 提交错误报告。

    这将是生产环境的初始（并且可能永远是）默认设置。

    ignore

    完全禁用 API 响应体验证。这是以防我们搞砸了的逃生舱口。

注意

开发用于收集这些 JSON Schema 模式并生成 OpenAPI 模式的工具不会在 Cinder 内部开发，因此本规范不涵盖这些内容。Cinder 将仅仅使用生成的工具来用于文档。

备选方案

  • 使用不同的工具

    OpenAPI 被选择是因为它是目前可用的最广泛使用的 API 描述语言，并且与我们现有使用 JSON Schema 进行 API 验证的方式相匹配。

  • 将这些规范维护在树外

    这可以防止我们在每次提交到 Cinder 时测试这些规范，并且意味着可以跨多个团队传播的工作集中在一个小团队上。

数据模型影响

无。

REST API 影响

不会有直接的 REST API 影响。如果用户设置 [api] response_validation = error 并遇到无效响应，他们将看到 HTTP 500 错误，但是，我们不会鼓励在生产环境中使用此选项，而是会专注于在 CI 中自己验证这些内容。

我们可能会希望解决在添加模式时发现的问题，但这项工作被认为是次要的，可以单独解决。

安全影响

无。

Active/Active HA 影响

无。

通知影响

无。

其他最终用户影响

这对于对开发 OpenStack 客户端和绑定的用户非常有益。特别是，这应该（在初始代码生成工作之后）减少 SDK 团队以及致力于客户端工具（例如 Gophercloud 团队）的 OpenStack 外部团队的工作量。

性能影响

启用验证时，由于我们将现在验证所有 API 资源的请求和响应，因此对 API 性能的影响将是最小的。鉴于我们已经广泛使用 JSON Schema 进行 API 验证，预计这不应该是一个重要问题。此外，我们不会建议在生产环境中启用此选项。

其他部署者影响

如前所述，将有一个新的配置选项，[api] response_validation。操作员可能会在他们的日志中看到增加的警告，因为模式不完整，但是，我们 CI 覆盖范围应该可以消除大多数（如果不是全部）这些问题。

开发人员影响

致力于 API 微版本的开发人员现在将被鼓励提供请求和响应的 JSON Schema 模式。

实现

负责人

主要负责人

stephenfinucane

其他贡献者

gtema

工作项

  • 添加缺少的请求体模式

  • 添加测试以验证请求体模式的存在

  • 添加缺少的查询字符串模式

  • 添加测试以验证查询字符串模式的存在

  • 添加响应体模式

  • 添加装饰器以根据响应验证响应体模式

  • 添加测试以验证响应体模式的存在

  • 更新 doc/source/contributor/api_microversion_dev.rst 以包含要求任何贡献需要新微版本的更改的人员预计提供请求和响应模式

依赖项

OpenAPI 文档的实际生成将通过一个单独的工具来实现。尚未确定该工具是否将存在于现有项目（例如 os_api_ref 或 openstacksdk）中，或者存在于全新的项目中。无论如何，可以预见的是，该工具将以一致和文档化的方式处理 OpenStack 特定的细微差别，例如与 OpenAPI 概念不完全对应的微版本。

测试

单元测试将确保最终存在请求体、查询字符串和响应体的模式。

单元、功能和集成测试将共同确保响应体模式与通过将 [api] response_validation 设置为 error 生成的实际响应匹配。

文档影响

最初不会有任何影响，因为我们将继续像以前一样使用 os_api_ref 作为我们的 api-ref 文档。最终我们将替换或扩展此扩展以从我们的 OpenAPI 模式生成文档。

参考资料

无。

历史

修订

发布名称

描述

2025.01

引入

2026.01

重新提出