From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: <erik@hollensbe.org> 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 E381B61D09 for <pve-devel@lists.proxmox.com>; Fri, 18 Dec 2020 12:27:59 +0100 (CET) Received: from firstgate.proxmox.com (localhost [127.0.0.1]) by firstgate.proxmox.com (Proxmox) with ESMTP id C95DD2F5E9 for <pve-devel@lists.proxmox.com>; Fri, 18 Dec 2020 12:27:29 +0100 (CET) Received: from mail-oi1-x236.google.com (mail-oi1-x236.google.com [IPv6:2607:f8b0:4864:20::236]) (using TLSv1.3 with cipher TLS_AES_128_GCM_SHA256 (128/128 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 A0A302F5D4 for <pve-devel@lists.proxmox.com>; Fri, 18 Dec 2020 12:27:28 +0100 (CET) Received: by mail-oi1-x236.google.com with SMTP id s75so2488251oih.1 for <pve-devel@lists.proxmox.com>; Fri, 18 Dec 2020 03:27:28 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=hollensbe-org.20150623.gappssmtp.com; s=20150623; h=mime-version:references:in-reply-to:from:date:message-id:subject:to :cc; bh=isenP/slaVbPwDJGYoPgj/N7ur11s1WEISJVMBwZFns=; b=bhKJ4yvLh0pTySK3L8HpLE8DOUJFppW7BxZzIEesah4LccBfBx7wbtBQKtvdFrva9C WVSy8coGnwaC+SXW8WKb/18TmrZHiookD8o7l6QAh1P8xNyVqQpI7gKBTYWH7fg+1ZJt JwIxxSEtpz4dEyjOoMVtWo9Pzb87DrRh6a6V+UD3JK3hBGf8lNkXR02n+QEtw7exQpYU FaTXFQil/mOkm+TFHIkWYERX/wc/isXre4OtkHJYmK2NdBO7Eou5v/61z8M3PjjDiS7I zPQEIMgfmRl8kq3ISKV/+bewvizeg3MBbx1gTmLXNF+9uJtBuMT6j0aHTgVyaBp6euU8 AZ0Q== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:mime-version:references:in-reply-to:from:date :message-id:subject:to:cc; bh=isenP/slaVbPwDJGYoPgj/N7ur11s1WEISJVMBwZFns=; b=pwPWVaikHe+b+04FRPisngk+/XG9nKsH0fntv2i/4AlKNVEDFtBm2ct8gz5QCNpXK3 XUkwz2uYpHz/2P5hrhwK7razfGKARXeLq8xHzCGCix50M3NFpjeFIkghTlATlhEEpCWS z/a/pOKJ7PoyFb8tWGMcoEDii5TGLqAEVBghjTZwLgIBjpEcW9MuA/ZBHxejqRRrXahM MgFY4+reMHkibi4YiK3Rn1L4MJTaSl52YJhOOnI56pa2MkkoWjyfMZ5UNBW4/3QKKZV3 Ai0zv8r8j/hg4dzP20C2h8KxLw7sZ3XjtYEjmNhuvPX4d8zaLHSs4qqLd4VB58Cr7l3L cL2A== X-Gm-Message-State: AOAM530eF04nLMMBABz0ED7RcPL7IfDCyc2QkYkeUbV1fpLdQHe4Zo50 6iv130gYlpYJRNTsL5DRjJgmSKcqFkBHcYJPSeujfA== X-Google-Smtp-Source: ABdhPJxYwa7odhiiG1SfWhc4Z1g0RcNWkYF8DYkJN63peYvG2R39Vh0yHileNUe848v+8j02E6xhM6C813wuM6SyjQc= X-Received: by 2002:aca:fc8d:: with SMTP id a135mr2392707oii.87.1608290841214; Fri, 18 Dec 2020 03:27:21 -0800 (PST) MIME-Version: 1.0 References: <CADHGEEKK-nzX6QDmu-4eqTDNhoQd54iLHL7891mJ4Arj6C7OMQ@mail.gmail.com> <4863e56a-6841-81cd-9d58-b1924d74e7da@proxmox.com> In-Reply-To: <4863e56a-6841-81cd-9d58-b1924d74e7da@proxmox.com> From: Erik Hollensbe <erik@hollensbe.org> Date: Fri, 18 Dec 2020 03:27:14 -0800 Message-ID: <CADHGEE+ERMaTOKQAUfJegCceD8iC-2nK3Nf96XMwfgniUkURWw@mail.gmail.com> To: Thomas Lamprecht <t.lamprecht@proxmox.com> Cc: Proxmox VE development discussion <pve-devel@lists.proxmox.com> X-SPAM-LEVEL: Spam detection results: 0 AWL -0.000 Adjusted score from AWL reputation of From: address DKIM_SIGNED 0.1 Message has a DKIM or DK signature, not necessarily valid DKIM_VALID -0.1 Message has at least one valid DKIM or DK signature HTML_MESSAGE 0.001 HTML included in message RCVD_IN_DNSWL_NONE -0.0001 Sender listed at https://www.dnswl.org/, no trust SPF_HELO_NONE 0.001 SPF: HELO does not publish an SPF Record SPF_NONE 0.001 SPF: sender does not publish an 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. [swagger.io, github.io, proxmox.com] Content-Type: text/plain; charset="UTF-8" X-Content-Filtered-By: Mailman/MimeDel 2.1.29 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 11:27:59 -0000 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. On Fri, Dec 18, 2020 at 2:02 AM Thomas Lamprecht <t.lamprecht@proxmox.com> 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 > >