codegenerator/README.rst

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:

• Nova
• Neutron
• Cinder
• Glance
• Keystone
• Octavia

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 ../nova

With Nova installed, we can now run openstack-codegenerator:

$ openstack-codegenerator \
    --work-dir wrk --target openapi-spec --service-type compute \
    --validate

If 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-ref

Note

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
    --validate

Your 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.