From mboxrd@z Thu Jan  1 00:00:00 1970
Return-Path: <t.lamprecht@proxmox.com>
Received: from firstgate.proxmox.com (firstgate.proxmox.com [212.224.123.68])
 (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)
 key-exchange X25519 server-signature RSA-PSS (2048 bits))
 (No client certificate requested)
 by lists.proxmox.com (Postfix) with ESMTPS id 1C48B61C2D
 for <pve-devel@lists.proxmox.com>; Fri, 18 Dec 2020 11:02:40 +0100 (CET)
Received: from firstgate.proxmox.com (localhost [127.0.0.1])
 by firstgate.proxmox.com (Proxmox) with ESMTP id 13EA92EAE5
 for <pve-devel@lists.proxmox.com>; Fri, 18 Dec 2020 11:02:40 +0100 (CET)
Received: from proxmox-new.maurer-it.com (proxmox-new.maurer-it.com
 [212.186.127.180])
 (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)
 key-exchange X25519 server-signature RSA-PSS (2048 bits))
 (No client certificate requested)
 by firstgate.proxmox.com (Proxmox) with ESMTPS id 605242EAD5
 for <pve-devel@lists.proxmox.com>; Fri, 18 Dec 2020 11:02:38 +0100 (CET)
Received: from proxmox-new.maurer-it.com (localhost.localdomain [127.0.0.1])
 by proxmox-new.maurer-it.com (Proxmox) with ESMTP id 28F2A452E5;
 Fri, 18 Dec 2020 11:02:38 +0100 (CET)
To: Proxmox VE development discussion <pve-devel@lists.proxmox.com>,
 Erik Hollensbe <erik@hollensbe.org>
References: <CADHGEEKK-nzX6QDmu-4eqTDNhoQd54iLHL7891mJ4Arj6C7OMQ@mail.gmail.com>
From: Thomas Lamprecht <t.lamprecht@proxmox.com>
Message-ID: <4863e56a-6841-81cd-9d58-b1924d74e7da@proxmox.com>
Date: Fri, 18 Dec 2020 11:02:35 +0100
User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:84.0) Gecko/20100101
 Thunderbird/84.0
MIME-Version: 1.0
In-Reply-To: <CADHGEEKK-nzX6QDmu-4eqTDNhoQd54iLHL7891mJ4Arj6C7OMQ@mail.gmail.com>
Content-Type: text/plain; charset=UTF-8
Content-Language: en-GB
Content-Transfer-Encoding: 7bit
X-SPAM-LEVEL: Spam detection results:  0
 AWL -0.065 Adjusted score from AWL reputation of From: address
 KAM_DMARC_STATUS 0.01 Test Rule for DKIM or SPF Failure with Strict Alignment
 NICE_REPLY_A           -0.001 Looks like a legit reply (A)
 RCVD_IN_DNSWL_MED        -2.3 Sender listed at https://www.dnswl.org/,
 medium trust
 SPF_HELO_NONE           0.001 SPF: HELO does not publish an SPF Record
 SPF_PASS               -0.001 SPF: sender matches SPF record
 URIBL_BLOCKED 0.001 ADMINISTRATOR NOTICE: The query to URIBL was blocked. See
 http://wiki.apache.org/spamassassin/DnsBlocklists#dnsbl-block for more
 information. [proxmox.com, github.io, swagger.io]
Subject: Re: [pve-devel] OpenAPI converter (similar to JSONSchema generator)
X-BeenThere: pve-devel@lists.proxmox.com
X-Mailman-Version: 2.1.29
Precedence: list
List-Id: Proxmox VE development discussion <pve-devel.lists.proxmox.com>
List-Unsubscribe: <https://lists.proxmox.com/cgi-bin/mailman/options/pve-devel>, 
 <mailto:pve-devel-request@lists.proxmox.com?subject=unsubscribe>
List-Archive: <http://lists.proxmox.com/pipermail/pve-devel/>
List-Post: <mailto:pve-devel@lists.proxmox.com>
List-Help: <mailto:pve-devel-request@lists.proxmox.com?subject=help>
List-Subscribe: <https://lists.proxmox.com/cgi-bin/mailman/listinfo/pve-devel>, 
 <mailto:pve-devel-request@lists.proxmox.com?subject=subscribe>
X-List-Received-Date: Fri, 18 Dec 2020 10:02:40 -0000

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