Guidance on how to convert Smithy models into AsyncAPI documents

[miguel-vila]

We are using Smithy to define domain events and wanted to produce valid AsyncAPI documents in order to render them nicely. We were thinking of reusing the JsonSchema conversion. We have done something like this by applying the conversion to the shapes that represent the events and doing some pre and post processing.

Pre processing includes:

• renaming shape ids to avoid collisions in the JsonSchema conversion (the conversion seems to ignore namespaces so there's a chance for collisions)

Post processing:

• updating the $refs so they point to #/components/messages or #/components/schemas depending on whether it's pointing to a message or not.
• wrapping messages in an async api message definition object (and adding an asyncapi trait that defines message headers).

There are some things about async api that we don't care about (e.g. servers). We mainly care about defining a valid components, and a valid channels field pointing to messages in that components.

We have implemented this conversion by applying the JsonSchema conversion and manipulating the resulting nodes, but I assume this is similar to the OpenAPI conversion, and there might be a better way. Do you have any guidance on how to avoid the collision problem and updating the $ref in a better way, maybe as part of the JsonSchema conversion itself?

[mtdowling]

This does sound like something that would need a dedicated converter and probably shouldn't attempt to reuse the OpenAPI converter (e.g., things like wrapping messages in an async API message definition object are going to be very specific to this). As for deconflicting refs, does the built-in deconflicting logic not work for you?

[miguel-vila]

@mtdowling thanks, for answering. For deconclicting refs, we hit the case in which two structures from different namespaces have the same name. Think the deconflicting logic doesn't work for structures or unions right?

[mtdowling]

Correct. They'd have to use different names. This is typically handled by defining shapes in the closure of a service and using rename on the service. There isn't a dedicated corollary in the JSON Schema converter. I suppose one could be added though.

[miguel-vila]

closing this issue for now. We worked around the naming collisions by doing a transformation in which we prefixed shape ids with their namespace, and then ran the JSON schema transformation, iirc.