Files
aa4d9e16b134bd1996daf718661ae84f42f3e774
codegenerator /README.rst

128 lines
4.3 KiB
ReStructuredText
Raw Normal View History

=======================
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.
YAML version support When exporting OpenAPI in YAML format we are exporting in YAML version 1.2, which is the latest. The problem with that is that there are tools that use the PyYAML [1] python package to read these files, and that package only supports YAML v1.1, which will lead to reading things incorrectly. An example is with booleans. In v1.1 a lot of values are considered as booleans (case insensitive): true, false, 1, 0, off, on, no, yes... But in v1.2 only true and false are considered booleans, so the others don't need to be quoted. As an example we were generating something like this: ``` os_hypervisors_with_servers: in: query name: with_servers schema: type: - boolean - string enum: - true - 'True' - 'TRUE' - 'true' - '1' - ON - On - on - YES - Yes - yes - false - 'False' - 'FALSE' - 'false' - '0' - OFF - Off - off - NO - No - no x-openstack: min-ver: '2.53' ``` Which is incorrectly interpreted by PyYAML like this: ``` enum: - true - 'True' - 'TRUE' - 'true' - '1' - true - true - true - true - true - true - false - 'False' - 'FALSE' - 'false' - '0' - false - false - false - false - false - false ``` ``` To fix this we enable our tool to output the specs in v1.1 with a new parameter `--yaml-version` so that when it's set to 1.1 it will quote all booleans that in v1.1 could be misinterpreted. [1]: https://pypi.org/project/PyYAML/ Change-Id: I7236f6a94ccb2e92a086c16895efa4dc557460c4
2025年05月20日 19:08:17 +02:00
.. note::
Beware that the output YAML file follows version 1.2 of the YAML
specification and there are libraries, such as PyYAML, that only support
version 1.1 and will parse the contents incorrectly.
Option ``--yaml-version 1.1`` can be passed on the call to force the output
to use specification version 1.1.
There are a variety of options available, which you can view with the
``--help`` option.
.. todo: Expand on other targets, options.