Hacker News new | ask | show | jobs
by dsun180 2270 days ago
I would love if the definition of websockets would be added to OpenAPI https://github.com/OAI/OpenAPI-Specification/issues/523
1 comments

What would be the advantage of that? OpenAPI is designed for HTTP-based APIs; I'm sure an equivalent can be done for WebSockets?
I would be able to document websockets side by side with "normal" requests and then use the same tooling for code generation or validation.
That use case would seem to be better served by creating a new standard that references the other standard for its IDL and serialization format, and general semantics, while having a separate standard for any websocket-specific details.

That avoids having to amend the original standard for each new variation. If you get enough variants (probably in the neighborhood of 2-4), then it makes sense to go back and supersede the original standard by breaking out the high-level layers each into their own standard that's designed for inclusion in other standards. That way, for instance, your async-Bluetooth standard doesn't have to refer to any document that gets bogged down in HTTP/1.1-specific messaging semantics. It's not worth re-factoring your standards stack the first time you reuse a standard, but you don't want some big spaghetti tangle of standards, either.