2cebebd4d6
- add services added recently - add info about sdk/cli/tui that are generated using codegenerator. Change-Id: Id41a3262be58deefd1f127a4c1a0df0b3b2e0aec
120 lines
4.0 KiB
ReStructuredText
120 lines
4.0 KiB
ReStructuredText
=======================
|
|
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 <https://github.com/gtema/openstack>`_.
|
|
|
|
.. 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:
|
|
|
|
.. code-block:: shell
|
|
|
|
$ 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:
|
|
|
|
.. code-block:: shell
|
|
|
|
$ 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``:
|
|
|
|
.. code-block:: shell
|
|
|
|
$ 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:
|
|
|
|
.. code-block:: shell
|
|
|
|
$ 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.
|
|
|
|
.. __: https://governance.openstack.org/tc/reference/project-testing-interface.html
|
|
|
|
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:
|
|
|
|
.. code-block:: shell
|
|
|
|
$ 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.
|
|
|
|
.. todo: Expand on other targets, options.
|