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 B92A961FC1 for ; Fri, 18 Dec 2020 14:13:01 +0100 (CET) Received: from firstgate.proxmox.com (localhost [127.0.0.1]) by firstgate.proxmox.com (Proxmox) with ESMTP id AE74094BA for ; Fri, 18 Dec 2020 14:12:31 +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) server-digest SHA256) (No client certificate requested) by firstgate.proxmox.com (Proxmox) with ESMTPS id B4A3594AC for ; Fri, 18 Dec 2020 14:12:30 +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 8678145383; Fri, 18 Dec 2020 14:12:30 +0100 (CET) To: Erik Hollensbe Cc: Proxmox VE development discussion References: <4863e56a-6841-81cd-9d58-b1924d74e7da@proxmox.com> From: Thomas Lamprecht Message-ID: Date: Fri, 18 Dec 2020 14:12:28 +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. [github.io, swagger.io, proxmox.com] 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 13:13:01 -0000 On 18/12/2020 12:27, Erik Hollensbe wrote: > Thanks for your assistance! I will look into these things over the weekend. > > As for the swagger endpoint, yes, more or less, I was going to assume there could be a /api2/swagger.json or similar route that could resolve to the API definition. > I'd mount it under `/schema/openapi` or maybe `/meta/openapi` as FWICT, this does not needs to be swagger specific, they just understand the openAPI spec. The /api2// then gets always prefixed, can be `json`, `html` (bootstrap backed API "debug" helper) or `extjs` (nested format tailored to our web interface framework). For generation I'd like to have this cached in `/var/lib/pve-manager` or so, can be updated by pve-manager through the `pve-api-updates` debian packaging trigger we already use, this way accessing that endpoint is fast and correct as it does not needs to dump it on demand. Note also that we do already some API dumping and use that, the pve-docs api viewer[0] is based on similar functionality, there we generate a JS file[1] with is basically a JSON structure. [0]: https://pve.proxmox.com/pve-docs/api-viewer/index.html#/nodes/{node} [1]: https://git.proxmox.com/?p=pve-docs.git;a=blob;f=api-viewer/apidata.js;h=a8f41de3f084219727581ae7a59ab6f176756890;hb=60077fc155c73905009c57874bffca1ec1fff49f > On Fri, Dec 18, 2020 at 2:02 AM Thomas Lamprecht > wrote: > > 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 >