On Fri, Sep 1, 2023, 15:42 <smooney@redhat.com> wrote:
On Thu, 2023-08-31 at 18:36 +0200, Artem Goncharov wrote:
> >
> > Just an fyi we have jsonschema schmas stored in python dicts for every
> > api in nova
> > https://github.com/openstack/nova/blob/4490c8bc8461a56a96cdaa08020c9e25ebe8f087/nova/api/openstack/compute/schemas/migrate_server.py#L38-L74
> >
> > we use them in our api tests with eh API scamples which are use both
> > as test and to generate docs
> > https://github.com/openstack/nova/tree/master/doc/api_samples/server-migrations
> >
> > every time we make an api change we add an api sample and add a secma
> > for that micorversion.
> >
> > These schemas are also use in the api to validate the requests
> > https://github.com/openstack/nova/blob/master/nova/api/openstack/compute/migrate_server.py#L84-L90
> >
> > so a lot of the data (boht on the spec  side an confromance side)
> > exits but not in a form that is directly  usabel to export openapi
> > formated documents.
> Thanks Sean, I know that and because of that I mentioned that nova is already using jsonschema. That is more or less
> exactly the point that I want to have a discussion on making this standard by the projects and do this generally with
> the openapi spec instead of bunch of unconnected schemas so that our own lives become hopefully easier.
ya i wanted to highlight that for you and others to see how they can and are currently used.
if we were to standatise this acroos services what i would want to see is the exesitign schemas ported to openapi schema
files which we would then import and uses for our validation.

Actually I have done in my poc nearly that: taken schema (as example, not literally) from nova code and integrated it into the spec. Surely it would be possible as you suggested to take schemas from the current code and construct them into the spec while we learn on how to have our middleware to locate them from the overall spec.

Generally openapi helps us (from 3.1) not to loose info, but vice versa extend and combine schemas into a full description of the operation how consumer is supposed to use it (what is the url, what are the parameters, what is the response(s)) with descriptions for each of those elements that are used for rendering docs and helpstrings.