search

asyncapi / spec

The AsyncAPI specification allows you to create machine-readable definitions of your asynchronous APIs.
https://www.asyncapi.com
Apache License 2.0
4.24k stars 269 forks source link

x-scheme: custom schemes #91

Closed mattheworiordan closed 5 years ago

mattheworiordan commented 6 years ago

Most standards that evolve quickly, follow innovation and adoption of the developers using those standards and the extensions they add. I realise the AsyncAPI spec does already support extensions in the form x-*, which is a good common convention.

However, looking specifically at server.scheme, it states:

"REQUIRED. The scheme this URL supports for connection. The value MUST be one of the following: kafka, kafka-secure, amqp, amqps, mqtt, secure-mqtt, ws, wss, stomp, stomps, jms".

I have seen a lot of other popular protocols being used such as Socket.io (loosely equivalent to ws I suppose), Nats (similar to STOMP/AMQP), Faye etc. and even some proprietary protocols that are popular.

Do you think it would be sensible to change this to:

"REQUIRED. The scheme this URL supports for connection. The value MUST be one of the following: kafka, kafka-secure, amqp, amqps, mqtt, secure-mqtt, ws, wss, stomp, stomps, jms, or may include an unsupported scheme as an extension in the format x-[scheme]."

I would assume that there is really no need to even specify that x-[scheme] may not be supported by the consumer, as the spec itself does not require that every scheme is supported anyway by every consumer as that would make it impractical for anyone to implement a client.

WDYT?

fmvilas commented 6 years ago

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 commented 6 years ago

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

fmvilas commented 6 years ago

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 commented 6 years ago

Ok, here goes :)

beatkyo commented 5 years ago

@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 commented 5 years ago

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

MikeRalphson commented 5 years ago

See also https://github.com/OAI/OpenAPI-Specification/pull/1812

fmvilas commented 5 years ago

🤔 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 commented 5 years ago

@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 commented 5 years ago

Oh I see. Thanks for explaining!

asyncapi-bot commented 3 years ago

:tada: This issue has been resolved in version 1.0.0 :tada:

The release is available on GitHub release

Your semantic-release bot :package::rocket: