Generator: Feedback about websocket client code generation

[bali182]

This is a follow-up for https://github.com/asyncapi/asyncapi/issues/98 . I attempted the client side code generator and it seemed fairly intuitive for the most part.

• I tried to do write the generator for this schema: https://github.com/asyncapi/asyncapi/blob/master/test/docs/slack-rtm.yml
• I used this for reference when unsure about parts of the schema: https://github.com/asyncapi/asyncapi/blob/master/README.md
• And here is what I can currently generate (not finished): https://github.com/bali182/asyncapi-ws-to-ts/blob/master/slackApi.ts

I have a few points of feedback (mind that this is for the websocket version, but some of this might be relevant for other protocols too).

1. It would be beneficial to add the concept of operationId in OpenAPI 3.0 to Message Object. In the Slack example both the send and receive list in the events object were refs, and the name of the refs could be used as method names. However these fields allow inline Message Objects, and in this case the method name cannot be inferred.
2. Make it possible to discriminate payloads (Message Object payloads). In the example I could do this by using the enum constants in payloads with a single possible value (type and subtype). But in case this is not available, it can be very costly to validate the full schema just to determine what type of message it is.
3. This might be just a problem with the slack schema, but according to the json schema spec, any part of the schema that doesn't have the "required": true field set, is not required, and can be ommited. In the slack schema all fields are optional.

[fmvilas]

Wow! Thanks for the great feedback @bali182! The resulting code is starting to look nice. Maybe a bit too bloated, but because the Slack API is also very big. Also, I love the work you did on defining the schema with TypeScript 👏

1. It would be beneficial to add the concept of operationId in OpenAPI 3.0 to Message Object.

Completely agree. This is gonna be solved in the next version: https://github.com/asyncapi/asyncapi/issues/77. Hopefully soon.

1. Make it possible to discriminate payloads (Message Object payloads). ... But in case this is not available, it can be very costly to validate the full schema just to determine what type of message it is.

In Websockets, how do you discriminate messages if it's not by looking at a field in the payload? AFAIK, you can't send headers in a message.

1. This might be just a problem with the slack schema, but according to the json schema spec, any part of the schema that doesn't have the "required": true field set, is not required, and can be ommited. In the slack schema all fields are optional.

Correct, this is just a problem with my Slack example.

[bali182]

Cool, the operationId (or silmilar) was the my biggest issue! Thanks for the compliments on the typescript stuff, it has been in the works for the while, I was doing the same for OpenAPI...

As for message discrimination, this might be a stretch but hear me out :) If we would want to force the schema for the incoming messages into a type system it would be something like this right?

type IncomingMessage = HelloPayload | AccountsChangedPayload | BotChangedPayload ...

So in terms of json schema this could be expressed as

receiveMessageSchema:
  oneOf: // or anyOf not 100 sure about semantics
    - $ref: '#/components/messages/HelloPayload'
    - $ref: '#/components/messages/AccountsChangedPayload'
    - $ref: '#/components/messages/BotChangedPayload'

And if this is the case we could add an optional discriminator property which as far as found online is already part of json schema:

  discriminator:
    propertyName: type
    mapping:
      hello: '#/components/messages/HelloPayload'
      accounts_changed: '#/components/messages/AccountsChangedPayload'
      bot_changed: '#/components/messages/BotChangedPayload'

I also added an example on how I imagine usage of the generated stuff, not sure what you think: https://github.com/bali182/asyncapi-ws-to-ts/blob/master/slackApiWithWs.ts

But optimizing for the most common usecases could also work (that's what I did for the slack example) in case you think it's too specific.

[bali182]

Just out of curiosity, are there any examples out there for the channeled (topiced if thats a word) forms of communication? What are the usecases that inspired having the asyncapi format? How do clients/servers look like? It seems like websocket is not the main targeted platform as I was thinking initially :)

[fmvilas]

Yeah, forgot about the discriminator feature of jsonschema. Not sure how it works, to be honest. I'll have to read more about it.

Regarding examples, you can find an example with topics here: https://github.com/asyncapi/asyncapi/blob/master/test/docs/sample.yml.

There are a few examples in this directory: https://github.com/asyncapi/asyncapi/tree/master/test/docs.

This is an example of a Node.js server generator: https://github.com/asyncapi/node-codegen. @rmelian and @ibaca are working on Java generators here: https://github.com/asyncapi/asyncapi/issues/18.

And you're right, the main platforms were message brokers, initially RabbitMQ and Kafka. Websockets support came afterward, in version 1.2.0. We're working on creating documentation with reference architectures where people can see examples of the most common use cases.

[fmvilas]

BTW, this is looking great! Very simple to read :)

[bali182]

Great, thanks, I will check those tools too, to get a sense of what the features are other than events :)

[MikeRalphson]

Just a note that discriminator is defined by OpenAPI and not JSON Schema.

[bali182]

@MikeRalphson oops, my bad. It still seems like a useful concept for this usecase.

[bali182]

@fmvilas Added a sample server/client with the slack schema just for fun :D https://github.com/bali182/asyncapi-ws-to-ts/blob/master/README.md#run-sample

[fmvilas]

Nice! That looks great! 👏

[github-actions[bot]]

This issue has been automatically marked as stale because it has not had recent activity :sleeping:
It will be closed in 30 days if no further activity occurs. To unstale this issue, add a comment with detailed explanation.
Thank you for your contributions :heart: