Confusions about OpenAPI, AsyncAPI and Websockets for client SDK

[ChristianVaughn]

I have been reading up on people asking about websocket proposals for OpenAPI, and I am confused on if OpenAPI or AsyncAPI can actually accomplish what I'm looking for.

I have a client SDK I am trying to autogenerate via one of these API specifications, but our SDK uses both websockets and HTTP Rest calls. The SDK default uses websockets with callbacks to act as a request-response. If the socket connection is lost, then the SDK falls back to the REST calls. From what I understand OpenAPI doesn't support websockets, but AsyncAPI doesn't have as robust of HTTP Rest support or the variety of language client generators.

Curious what people are doing in situations like this? I know I have seen a few people in issues with similar situations. My initial thought was to use OpenAPI specification and generators to make client SDKs then modify the generated files for socket support. Any help would be appreciated and sorry if my understanding of either specification is not accurate.

[flaksp]

You can write a specification in your own proprietary format and then convert it to both OpenAPI and AsyncAPI specifications using some script. It should be kinda trivial task since both specs are just large JSONs and they pretty similar. Just pick common things from both specs and then create your own specification format. You may also write your own JSON Schema and define it in $schema keyword which will be nice for IDE autocompletion, and for validation you too — with help of Ajv JSON Schema validator or something similar. It would be useful at least for documentation purposes (rendering a spec as HTML).

You can also create your own proprietary code generation solution. It's not that hard to implement a code generator (using AST-based generation, not templates which will break your brain!), especially if you are not setting a goal to cover 100% features available in JSON Schema and OpenAPI/AsyncAPI (there are no generators that support advanced features of all these specs). And it would be much easier to generate a code from your proprietary spec I mentioned in previous paragraph. All these specs weren't designed to provide first-class support for code generating use-cases, that's why it's mostly impossible to accomplish 100% feature coverage. That's how our team fulfilled our specific code generation needs — we just wrote our own generator using our proprietary spec format (which uses JSON Schema for describing data).

[handrews]

Looks like this was answered, and I know we have issues tracking websocket requests (as mentioned by the OP) so I'm going to go ahead and close this.