items
As explained in the documentation `arrays` have an `items` section, and
arrays that can have arbitrary values are defined like this [1]:
```
type: array
items: {}
```
In the cinder schemas we have a couple of cases where we are defining an
`array` without `items`, all other arrays in the openapi codebase seem
to be right.
In this patch we fix these issues and introduce code in the
`_sanitize_schema` to detect future cases of this issue and fix the
schema automatically for the output.
[1]: https://swagger.io/docs/specification/v3_0/data-models/data-types/#mixed-type-arrays
Change-Id: I49cadcccf64ed9699a4b41674109b4afbfa1e106
OpenStack CodeGenerator
Primary goal of the project is to simplify maintainers life by generating complete or at least parts of the code.
CodeGenerator is able to generate OpenAPI specs for certain services by inspecting their code and API Reference (api-ref) documentation. This requires the service package be installed in the environment where the generator is running. The generator then tries to initialize the service application and for supported services scans for the exposed operations. At the moment the following services are covered:
- Cinder
- Designate
- Glance
- Ironic
- Keystone
- Magnum
- Manila
- Neutron
- Nova
- Octavia
- Placement
In addition to building OpenAPI specs CodeGenerator is also used to build SDK, CLI and TUI in Rust for OpenStack. Those live currently in this GitHub repository.
Note
CodeGenerator is not intended to be used outside of OpenStack context (while maybe it will even work). It is used primarily in the automatic pipelines. For this reason it is not published to the PyPy.
Getting started
CodeGenerator is not currently packaged on PyPI (and may never be). As a result, you must install from Git. For example:
$ git clone https://opendev.org/openstack/codegenerator
$ cd codegenerator
$ virtualenv .venv
$ source .venv/bin/activate
$ pip install -e .Once installed, you can use the openstack-codegenerator
for all operations. The openstack-codegenerator provides a
number of targets. These correspond to the various steps
required to get a functioning OpenAPI schema. The first target is the
openapi-spec target. This will generate an initial OpenAPI
schema through inspection of the chosen projects code and api-ref
documentation.
Let's generate an OpenAPI schema for the Compute service, Nova. To do this, we first need to install Nova in the same virtualenv that we have installed CodeGenerator in. Let's pull the Nova repo down locally and install it:
$ cd ..
$ git clone https://opendev.org/openstack/nova
$ cd -
$ pip install \
-c https://releases.openstack.org/constraints/upper/master \
-r ../nova/requirements.txt
$ pip install -e ../novaWith Nova installed, we can now run
openstack-codegenerator:
$ openstack-codegenerator \
--work-dir wrk --target openapi-spec --service-type compute \
--validateIf you look in the path indicated by the --work-dir
argument, you will find a OpenAPI schema! However, this schema is rather
incomplete. That's because we inspected the Nova code but not the
api-ref docs. To do that, we need to pass a path to our docs, which
means we need to build the docs locally. Let's do this:
$ cd ../nova
$ tox -e api-refNote
The api-ref target should be consistent across
projects. However, it's not currently part of the Project Testing Interface__ so this isn't
guaranteed. If you find this target doesn't exist, look at your
project's tox.ini file for clues.
You should now have the documentation built in HTML format and
available in the api-ref/build/html directory. Let's change
back to the codegenerator directory and run
openstack-codegenerator again, this time with an additional
--api-ref-src argument:
$ cde ../code-generator
$ openstack-codegenerator \
--work-dir wrk --target openapi-spec --service-type compute \
--api-ref-src ../nova/api-ref/build/html/index.html \
--validateYour API documentation should now be looking much better. You'll even have documentation available inline.
There are a variety of options available, which you can view with the
--help option.