OpenAPI Schemas

https://blueprints.launchpad.net/nova/+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 是我将与之交互的。

As an end user, I want statically viewable documentation hosted as part of the existing docs site without requiring a running instance of Nova.

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

As a Nova developer, I would like to have a verified API specification that I can use should I need to replace the web framework/libraries we use in the event they are no longer maintained.

提议的变更

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

• Add a new decorator for removed APIs and actions

  We have a number of APIs and actions that no longer have backing code and return HTTP 410 (Gone) or HTTP 400 (Bad Request), respectively. We will not add schemas for these in the initial attempt at this so we need some mechanism to indicate this. We will add a new removed decorator that will highlight these removed APIs and indicate the version they were removed in and the reason for their removal. We can later use this as a heuristic in our tests to skip schema checks for these methods.

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

  There is already good coverage of both request bodies and query string parameters but it is not complete. A list of incomplete schemas is given at the end of this section. The additional schemas will merely validate what is already allowed, which will mean extensive use of "additionalProperties": true or empty schemas. Put another way, an API that currently ignores unexpected request body fields or query string parameters will continue to ignore them. We may wish to make these stricter, as we did for most APIs in microversion 2.75, but that is a separate issue that should be addressed separately.

  Once these specs are added, tests will be added to ensure all non-deprecated and non-removed API resources have appropriate schemas.

• 添加响应体模式

  These will be sourced from existing OpenAPI schemas, currently published at github.com/gtema/openstack-openapi, from Tempest’s API schemas, and where necessary from new schemas auto-generated from JSON response bodies generated in tests and manually modified handle things like enum values.

  Once these are added, tests will be added to ensure all non-deprecated and non-removed API resources have appropriate response body schemas. In addition, we will add a new configuration option that will control how we do verification at the API layer, [api] response_validation. This will be an enum value with three options

  error

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

  This will be the default in CI i.e. for our unit, functional and integration tests. This should not be used in production. The help text of the option will indicate this and we will set the advanced option.

  warn

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

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

  ignore

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

注意

The development of tooling required to gather these JSON Schema schemas and generate an OpenAPI schema will not be developed inside Nova and is therefore not covered by this spec. Nova will merely consume the resulting tooling for use in documentation. It is intended that the same tool will be usable across any OpenStack project that uses the same web frameworks (in Nova’s case, WebOb + Routes).

注意

The impact of middleware that modifies either the request or response will not be accounted for in this change. This is because these are configurable and they cannot be guaranteed to exist in a given deployment. Examples include the sizelimit middleware from oslo.middlware and the auth_token middleware from keystonemiddleware.

备选方案

• 使用不同的工具

  We could use a different tool than OpenAPI to publish our specs. In a manner of speaking we already do this - albeit not in a machine-readable manner - through our use of os-api-ref.

  This idea has been rejected because OpenAPI is clearly the best tool for the It is the most widely used API description language available today and aligns well with our existing use of JSON Schema for API validation. While it does not support OpenStack’s microversion API design pattern out-of-the-box, previous experiments have demonstrated that it is extensible enough to add this.

• 将这些规范维护在树外

  We could use a separate repo to store and maintain specs for Nova and the other OpenStack services.

  This idea has been rejected because it prevents us testing the specs on each commit to Nova and means work that could be spread across multiple teams is instead focused on one small team. It will result in more bugs and a lag between changes to the Nova API and changes to the out-of-tree specs. It will result in duplication of effort across Nova, Tempest, and the specs projects.

• Publish the spec via an API resource rather than in our docs

  We could publish the spec via a new, unversioned API endpoint such as /spec. A GET request to this would return the full spec, either statically generated at deployment time or dynamically generated (and then cached) at runtime.

  这个提案被拒绝，因为它带来的优势有限，却存在多个缺点。Nova 的 API 被设计为向后兼容且不可扩展。因此，使用最新规范的用户应该能够使用它与运行支持微版本的 Nova 版本的任何 OpenStack 环境进行通信。 此外，我们预计规范的“主”版本将随着收紧、改进文档以及修复错误或失误而不断改进。 我们希望规范的使用者能够立即看到这些变化，而不是等待他们的部署更新。 最后，OpenStack 之前尝试过的可发现的 API，例如 Keystone 使用的 JSONHome 或 Glance 尝试发布的资源模式，在项目之外的采用率有限。 综上所述，这表明没有理由或优势去发布部署特定的规范，用户最好从 docs.openstack.org 上发布的 api-ref 文档中获取最新版本的规范（值得注意的是，该文档本身也是有意不带版本的）。

数据模型影响

无。

REST API 影响

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

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

安全影响

无。

通知影响

无。

其他最终用户影响

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

性能影响

There will be a minimal impact on API performance when validation is enabled as we will now verify both requests and responses for all API resources. Given our existing extensive use of JSON Schema for API validation, it is expected that this should not be a significant issue.

其他部署者影响

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

开发人员影响

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

升级影响

无。

实现

负责人

主要负责人

stephenfinucane

其他贡献者

gtema

功能联络人

无。

工作项

• 添加缺少的请求体模式

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

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

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

• 添加响应体模式

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

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

依赖项

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

测试

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

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

文档影响

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

参考资料

APIs missing schemas

These are the APIs that are currently (as of 2024-04-11, commit 1bca24aeb) missing API request body schemas and query string schemas.

Missing request body schemas

• AdminActionsController._inject_network_info

• AdminActionsController._reset_network

• AgentController.create

• AgentController.update

• BareMetalNodeController._add_interface

• BareMetalNodeController._remove_interface

• BareMetalNodeController.create

• CellsController.create

• CellsController.sync_instances

• CellsController.update

• CertificatesController.create

• CloudpipeController.create

• CloudpipeController.update

• ConsolesController.create

• DeferredDeleteController._force_delete

• DeferredDeleteController._restore

• FixedIPController.reserve

• FixedIPController.unreserve

• FloatingIPBulkController.create

• FloatingIPBulkController.update

• FloatingIPController.create

• FloatingIPBulkController.create

• FloatingIPBulkController.update

• FloatingIPController.create

• FloatingIPDNSDomainController.update

• FloatingIPDNSEntryController.update

• LockServerController._unlock

• NetworkAssociateActionController._associate_host

• NetworkAssociateActionController._disassociate_host_only

• NetworkAssociateActionController._disassociate_project_only

• NetworkController._disassociate_host_and_project

• NetworkController.add

• NetworkController.create

• PauseServerController._pause

• PauseServerController._unpause

• RemoteConsolesController.get_rdp_console

• RescueController._unrescue

• SecurityGroupActionController._addSecurityGroup

• SecurityGroupActionController._removeSecurityGroup

• SecurityGroupController.create

• SecurityGroupController.update

• SecurityGroupDefaultRulesController.create

• SecurityGroupRulesController.create

• ServersController._action_confirm_resize

• ServersController._action_revert_resize

• ServersController._start_server

• ServersController._stop_server

• ShelveController._shelve

• ShelveController._shelve_offload

• SuspendServerController._resume

• SuspendServerController._suspend

• TenantNetworkController.create

Missing request query string schemas

• AgentController.index

• AggregateController.index

• AggregateController.show

• AvailabilityZoneController.detail

• AvailabilityZoneController.index

• BareMetalNodeController.index

• BareMetalNodeController.show

• CellsController.capacities

• CellsController.detail

• CellsController.index

• CellsController.info

• CellsController.show

• CertificatesController.show

• CloudpipeController.index

• ConsoleAuthTokensController.show

• ConsolesController.index

• ConsolesController.show

• ExtensionInfoController.index

• ExtensionInfoController.show

• FixedIPController.show

• FlavorAccessController.index

• FlavorExtraSpecsController.index

• FlavorExtraSpecsController.show

• FlavorsController.show

• FloatingIPBulkController.index

• FloatingIPBulkController.show

• FloatingIPController.index

• FloatingIPController.show

• FloatingIPDNSDomainController.index

• FloatingIPDNSEntryController.show

• FloatingIPPoolsController.index

• FpingController.index

• FpingController.show

• HostController.reboot

• HostController.show

• HostController.shutdown

• HostController.startup

• HypervisorsController.detail

• HypervisorsController.index

• HypervisorsController.search

• HypervisorsController.servers

• HypervisorsController.show

• HypervisorsController.statistics

• HypervisorsController.uptime

• IPsController.index

• IPsController.show

• ImageMetadataController.index

• ImageMetadataController.show

• ImagesController.detail

• ImagesController.index

• ImagesController.show

• InstanceActionsController.index

• InstanceActionsController.show

• InstanceUsageAuditLogController.index

• InstanceUsageAuditLogController.show

• InterfaceAttachmentController.index

• InterfaceAttachmentController.show

• NetworkController.index

• NetworkController.show

• QuotaClassSetsController.show

• QuotaSetsController.defaults

• QuotaSetsController.detail

• QuotaSetsController.show

• SecurityGroupController.show

• SecurityGroupDefaultRulesController.index

• SecurityGroupDefaultRulesController.show

• ServerDiagnosticsController.index

• ServerGroupController.show

• ServerMetadataController.index

• ServerMetadataController.show

• ServerMigrationsController.index

• ServerMigrationsController.show

• ServerPasswordController.index

• ServerSecurityGroupController.index

• ServerTagsController.index

• ServerTagsController.show

• ServerTopologyController.index

• ServerVirtualInterfaceController.index

• ServersController.show

• SnapshotController.show

• TenantNetworkController.index

• TenantNetworkController.show

• VersionsController.show

• VolumeAttachmentController.show

• VolumeController.show

注意

We should emphasise that many - but not all - of the aforementioned APIs are either deprecated or removed. We may wish not to add schemas for these, though by doing so we will lose the ability to generate documentation or clients for these APIs from the OpenAPI spec.

历史

修订版

发布名称	描述
2024.2 达尔马提安	引入