Goal:

OpenAPI is an industry-standard, machine-readable format for describing RESTful and REST-like APIs. It is based on JSON Schema, which is already extensively used in OpenStack, and can be used to testing and validation APIs as well as document them. The combination self-validation and machine-readability provides an important advantage over the existing OpenStack-specific os-api-ref tooling and allows these schemas to be easily and accurately consumed by AI and client generation tooling. The effort to integrate OpenAPI schemas also provides an opportunity to rationalise our API machinery and remove or replace use of unmaintained libraries and utilities.

This epic tracks the addition of OpenAPI schemas to the OpenStack Cinder service, to complement those that have already been added to the Keystone service and are being added to the Nova and Ironic services.

Acceptance Criteria:

The addition of OpenAPI schemas will take place in multiple phases, which may stretch over more than one upstream release. Each of these phases can be considered a gate for the following phase(s):

• [Internal] Remaining references to the legacy v2 API should be removed and any code merged into the v3 controller. In addition, any use of auto-generated routes should be replaced with explicit method-path routing.
• All APIs that expect request query string parameters should have schemas for those parameters
• All APIs that expect request bodies should have schemas for those bodies
• All APIs that return response bodies should have schemas for those bodies
• [Bonus] The use os-api-ref should be replaced with the OpenAPI schema (this relies on external tooling)

Open questions:

(none)