x-scheme: custom schemes

[mattheworiordan]

x-scheme: custom schemes

[beatkyo]

@fmvilas I would like to add my 2 cts about tooling control. The way I see things, controlling code generators is the biggest mistake swagger ever made. Now (almost) every generator lives in a single repository under a single version. Trying to figure which version of the codegen is needed to generate code for a particular version of a framework for a particular version of a language is a nightmare.

Even more, first release of codegen supporting OAS 3.0 took 14 month (from spec release to codegen release) ! Reason for it is that every body needs to update their generator to OAS3 to make the release happen ... And guess what, not every generators in codegen is supporting OAS3.0. So in the end we have an official may-be supporting 'OAS3' codegen. I wont even bother try to figure how to use this thing ...

You probably noticed I have some personal grief with swagger codegen :D. I developed 4 generators at my company (kinda obsessed with api generation). And from this point of view I can tell you working with swagger 'tool control' is really really painful ... For the record the last generator I wrote only uses open api java model, everything else is custom (no mustache, no abstract codegen) and it is by far the cleanest of all. So I would advise you not to repeat the same pattern. I just discovered AsyncApi and I must admit it would be a great thing to have along OAS.

Other than that I am in favor of leaving scheme open to any value. User responsibility would be to pick the right tooling. Minimal expected behavior is to clearly state that scheme: abc is not supported by the tool.

[fmvilas]

That's a good point, Matt. I added a restriction on the number of protocols so that I could "control" how tooling evolves, but I don't think it makes sense anymore. Maybe it's time for server.scheme to be just a string without restrictions in its value, and it's gonna depend on your tooling if it's supported or not.

However, I must say that the idea of using the x-[scheme] sounds very good to me. After some time, we could grab a bunch of x-[scheme]'s and add them to the supported list.

[mattheworiordan]

@fmvilas 👍 for x-schemes until the naming at least is standardised.

[fmvilas]

Cool! You want it to be your first issue? :) Feel free to mark it for version 1.3.0 and create a PR. Also, don't forget to add it here and move it to In Progress whenever you're working on it.

[mattheworiordan]

Ok, here goes :)

[fmvilas]

Hey @mattheworiordan! How is this going? Would you still want to work on this issue?

[MikeRalphson]

See also OAI/OpenAPI-Specification#1812

[fmvilas]

🤔 is it the same thing @MikeRalphson? I think the one you linked is related to security schemes. This issue is about schemes as in "protocols".

[MikeRalphson]

@fmvilas sorry - it was more about the general approach of using custom as an enum entry and having a customType (or customScheme) property, rather than using x-* in the enum, which is difficult to validate. Though not all the OAI/TSC is in favour of this approach.

[fmvilas]

Oh I see. Thanks for explaining!

[asyncapi-bot]

🎉 This issue has been resolved in version 1.0.0 🎉

The release is available on GitHub release

Your semantic-release bot 📦🚀