support for OpenAPI v3 extensions

[newgene]

As you may know, we currently host a copy of openapi-gui on our SmartAPI project: http://smart-api.info/openapi-gui/. Thanks for making it available.

SmartAPI defines a set of OpenAPI extensions to support biomedical-field APIs, so we are wondering how much work is needed in order to add the extra "x-" extension fields into the openapi-gui web forms.

Ideally, it would be nice to allow us to define extra schemas in a separate file like "extensions.js" (under openapi-gui/data folder), then it can be merged into "jsonSchemaDraft4" defined in "static.js". Depending on how the rendering code works, those extra extension fields can then be rendered in the web forms.

[MikeRalphson]

Hi @newgene thanks for reaching out - have you seen the SEMOASA proposal for a machine-readable format for OpenAPI specification extensions?

As an example, if you create a SEMOASA document (format is still in flux) you would be able to render documentation such as this.

Enabling intelligent support for OpenAPI extensions in definition editors is one of the stated use-cases.

What I am thinking of currently is that the OpenAPI definition might include an extension pointing at an array of SEMOASA documents which define the extensions which are expected to be encountered. But there is no reason why you could not preload these and instantiate effectively a SmartAPI-gui.

At the moment the templates and field logic in OpenAPI-gui are fixed, but I think creating dynamic elements based on a schema-to-html translation should be possible.

Pinging @tedepstein, @RomanGotsiy, @brendo, @brylie, @EricWittmann for their thoughts.

[EricWittmann]

Although apicurio isn't mature enough yet to worry too much about how to render OAI extensions, in principle I think SEMOASA sounds like a great idea. Anything that can give editors (and documentation generators) more information about what a property might mean would be super helpful.

[tedepstein]

@newgene and @MikeRalphson ,

Yes, this is exactly the kind of use case I had in mind for SEMOASA. We'd like to provide a rich editing experience for OpenAPI extensions in our own API editors. And we'd like to promote SEMOASA as an open standard so that extensions can be supported in any compliant editing tool.

Tool providers have a lot of flexibility as to how they want to expose this functionality. For example:

• The configuration of the editor could be
  • baked-in, with a preset SEMOASA catalog; or
  • admin-configurable, e.g. as a startup parameter in the editor deployment; or
  • user-configurable in a user account, team account, "workspace" or "project" (if those abstractions exist); or
  • driven by embedded extension properties (now going "full meta," with extension properties that point to other SEMOASA extension description documents.)
• Users of the editor could simply point to one or more SEMOASA documents (through one of the above configuration mechanisms), and have full access to all of the specifications extensions defined therein. Or there could be another layer of configuration that lets the user specify which of those registered extensions they intend to use, so a catalog of 200 extensions doesn't have to mean 200 proposals in a code assist popup.

[newgene]

Great! Thank you all for pointing us to SEMOASA. It's exactly the piece I thought missing in the OpenAPI ecosystem. Glad you guys have stepped up and created one already. We will definitely look into it. And we are particularly interested to see a web-based API metadata editor, like openapi-gui, with the SEMOASA support.

[MikeRalphson]

Form-generation from a schema-like definition in vue.js:

https://jsfiddle.net/Herteby/ybqp8j0b/

Dynamic binding issue:

https://github.com/vuejs/vue/issues/1056

[MikeRalphson]

@newgene Just to let you know some progress is being made on this issue. Any help you can give towards a Semoasa document for your OAS extensions would be gratefully received.

[newgene]

@MikeRalphson thanks, we will give it a try.

[MikeRalphson]

@newgene sorry - that's just a teaser- the dynamically generated forms are working well, but I still need to do some work on the persistence layer behind it before it is released.

[newgene]

@MikeRalphson got it. We will continue watching this thread then :-)

[moon0326]

Hi,

Is there any progress on this one? https://github.com/Mermade/openapi-gui/issues/16#issuecomment-368436712 looked very promising

[MikeRalphson]

Hi @moon0326 - unfortunately not as yet, There's not really much to do (the persistence mechanism, and the importing of extension metadata) but the Semoasa spec (and usage of it) seems to have stalled somewhat and that kind of took the wind out of the sails of this feature. I will update here if I get time to get back to it. If you know vue.js and something about dynamic binding then help would be very much appreciated!

[moon0326]

@MikeRalphson Thank you for such a fast response. It's my fist time seeing this package. I will take a look!

[MikeRalphson]

Thanks @moon0326 the existing code is on the semoasa branch.