OpenAPI Schemas¶
https://bugs.launchpad.net/keystone/+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 是我将与之交互的。
作为最终用户，我希望能够静态查看托管在现有文档站点上的文档，而无需运行 Keystone 的实例。
作为 SDK/客户端开发人员，我希望能够自动生成绑定和客户端，从而提高一致性并最大限度地减少开发和维护这些工具所需的体力劳动。
作为 Keystone 开发人员，我希望拥有一个经过验证的 API 规范，以便在需要替换我们使用的库时可以使用，以防它们不再维护。
提议的变更¶
这项工作可以分解为几个不同的步骤
添加缺少的请求体和查询字符串模式
这些模式将仅仅验证已经允许的内容，这意味着广泛使用
"additionalProperties": true或空模式。一旦添加了这些模式，将添加测试以确保所有 API 资源都具有适当的模式。
添加响应体模式
这些将从现有的 OpenAPI 模式获取，目前发布在 https://opendev.org/openstack/codegenerator，以及从测试中生成的 JSON 响应体自动生成的模式，并手动修改以处理枚举值等内容。
一旦添加了这些模式，将添加测试以确保所有 API 资源都具有适当的响应体模式。此外，我们将添加一个新的配置选项，该选项将控制我们在 API 层进行验证的方式，
[api] response_validation。这将是一个枚举值，具有三个选项error如果 API 返回“无效”响应，则引发 HTTP 500（服务器错误）。
这将是 CI 中的默认设置，即对于我们的单元、功能和集成测试。最终，这也可以成为生产环境的默认设置。
warn记录关于“无效”响应的警告，提示操作记录针对 Nova 的错误报告。
这将是生产环境的初始（并且可能永远是）默认设置。
ignore完全禁用 API 响应体验证。这是以防我们搞砸了的逃生舱口。
注意
开发用于收集这些 JSON Schema 模式并生成 OpenAPI 模式的工具不会在 Keystone 内部开发，因此本规范不涵盖该工具。Keystone 将仅仅使用生成的工具来用于文档。
备选方案¶
使用不同的工具
OpenAPI 被选择是因为它是目前可用的最广泛使用的 API 描述语言，并且与我们现有使用 JSON Schema 进行 API 验证的方式相匹配。
将这些规范维护在树外
这可以防止我们在每次提交到 Keystone 时测试这些，并且意味着可以分散到多个团队的工作，而是集中在一个小团队上。
安全影响¶
无
通知影响¶
无
其他最终用户影响¶
这对于对开发 OpenStack 客户端和绑定的用户非常有益。特别是，这应该（在初始代码生成工作之后）减少 SDK 团队以及致力于客户端工具（例如 Gophercloud 团队）的 OpenStack 外部团队的工作量。
性能影响¶
由于我们将现在为所有 API 资源验证请求和响应，因此对 API 性能的影响将是最小的。鉴于我们已经广泛使用 JSON Schema 进行 API 验证，预计这不应该是一个重要问题。
其他部署者影响¶
无
开发人员影响¶
致力于 API 微版本的开发人员现在将被鼓励提供请求和响应的 JSON Schema 模式。
实现¶
负责人¶
- 主要负责人
gtema
工作项¶
添加缺少的请求体模式
添加测试以验证请求体模式的存在
添加缺少的查询字符串模式
添加测试以验证查询字符串模式的存在
添加响应体模式
添加装饰器以根据响应验证响应体模式
添加测试以验证响应体模式的存在
为在 OpenAPI 规范中使用的 API 方法和主体添加描述
依赖项¶
OpenAPI 文档的实际生成将通过一个单独的工具来实现。尚未确定该工具是否将存在于现有项目（例如 os_api_ref 或 openstacksdk）中，或者存在于全新的项目中。无论如何，可以预见的是，该工具将以一致和文档化的方式处理 OpenStack 特定的细微差别，例如与 OpenAPI 概念不完全对应的微版本。
文档影响¶
最初不会有任何影响，因为我们将继续像以前一样使用 os_api_ref 作为我们的 api-ref 文档。最终我们将替换或扩展此扩展以从我们的 OpenAPI 模式生成文档。
