[pve-devel] OpenAPI converter (similar to JSONSchema generator)

[Thomas Lamprecht]

Hi,


first, thanks for your interest in working on and improving Proxmox VE!

On 17/12/2020 05:45, Erik Hollensbe wrote:
> The specification is here and has similar semantics and goals to
> jsonschema, just really good codegen support:
> https://swagger.io/specification/
> 
> What I am proposing is a module that sits alongside the JSONSchema package
> and generates an openapi.json/swagger.json on http request, so that the
> client can either be dynamically configured or generated from a request to
> a server. It could also be served on proxmox's website for simpler
> generation.

You mean, you'd like to add a new API endpoint returning the schema in
openAPI format?

> 
> It looks like this is doable with the separation of concerns in JSONSchema
> and RESTHandler, since all the former does is extract data from the latter,
> unless I am misreading things. A swagger/openapi generator would do
> something similar. Swagger is just JSON as well, so there's no magic
> formatting or parsing that needs to take place.

JSONSchema and openAPI are closely related, so it should not be really hard
to do, albeit, we're not 100% JSONSchema compatible, meaning that we do not
support all of it and possible use some things which it has no support for
(on the latter I'd need to re-check closely though).

The code dumping it should live along side of JSONSchema in pve-common, but
the actual API endpoint (if that is what you want) has to go in pve-manager,
as only there we have all dependencies available for actual use.

> 
> I am comfortable (but rusty) in perl and can read your json schema code
> fine, and am willing to make the patches to generate the specification
> assuming this is OK and acceptable to the powers that be.

We have a wiki giving some pointers about build environment, code-style,
CLA, and sending patches - maybe it helps checking it out:

https://pve.proxmox.com/wiki/Developer_Documentation

> 
> The advantages are a healthy ecosystem of code generators (
> https://github.com/OpenAPITools/openapi-generator) and also documentation
> tools, like this one: https://redocly.github.io/redoc/.
> 
> I think the package could be delivered in a few weeks assuming a
> development environment is easy enough to get going.
> 

See the following readme for some rough instructions, note that just for the
perl development lots 
https://git.proxmox.com/?p=pve-common.git;a=blob_plain;f=README.dev;hb=HEAD

cheers,
Thomas