Expose generated Async API schema docs via FlowFuse UI

[joepavitt]

Extend #4919 to generate and expose the generated Async API yml in an easier to consume format, e.g. the static docs via generator

[joepavitt]

Initial investigations suggest we may need roll out our own generator here as the static generator is a time consuming script

[knolleary]

I'm going to look at what other options may exist rather than rolling our own - which could get quite involved.

The piece I haven't quite got straight in my head is how these docs integrate with the existing topic hierarchy view, and some of the proposed design enhancements that let you click around the topic tree and see additional information we have from those topics. Feels like two ways of doing the same thing.

This item is still firmly in the research/design/scoping phase, so it's hard to put an expected delivery date on it yet.

[joepavitt]

The piece I haven't quite got straight in my head is how these docs integrate with the existing topic hierarchy view, and some of the proposed design enhancements that let you click around the topic tree and see additional information we have from those topics. Feels like two ways of doing the same thing.

The key piece I had in mind is that the FlowFuse topic view will eventually become more interactive, allow you to add/remove manual topics and payload definitions/schemas.

The "Share" view would be a static asset that is used/shared when building out flows in Node-RED or interactive with the UNS.

In the same way that we have a "Dashboard Viewer", I would envision RBAC to the "View" of the schema to be different o the edit mode of the schema (FlowFuse UI)

[knolleary]

One of the issues with using an existing AsyncAPI based generator is that we don't currently have quite enough content in the automatically generated spec to be fully useful.

Our existing spec lists the topics - as 'channels'. Within AsyncAPI, you then list 'operations' against the channels - ie, what does it mean to publish to a given channel/topic, or what does a subscription to this channel get you. We don't currently include operations against the channels as that's a level of meta information we can't infer.

The AsyncAPI generator lists operations in its output, not channels.

I'm doing some more digging to see if we need can enhance our spec further with some sort of default placeholders, so that we can then make use of an existing generator in some form.

Increasing the sizing estimate on this task.