From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: 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 ; 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 ; 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 ; 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 , Erik Hollensbe References: From: Thomas Lamprecht 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: 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 List-Unsubscribe: , List-Archive: List-Post: List-Help: List-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