Support top-level documentation above /events

[JacobCrofts]

Describe your request

Events created with the /events resource do not support documentation. Ideally a description field would appear in the generated AsyncAPI file.

/events
"this does not produce a description"
POST

"This does produce documentation (with a caveat described below)"
event MyResourceEvent {
    /payload
        myResource: value-of MyResource
}
produces MyResourceEvent

One critical difference between these strategies is that the first produces generated docs that assume the event will be a flat list of attributes, whereas the second forces us to use a nested list. We have gone with the first strategy and have consumers already, so switching from a flat list to a nested list would be a breaking change.

This is what I mean:

# flat list:
{
  someAttribute: 1,
  someOtherAttribute: 2
}

# nested list:
{
  myResource: {
    someAttribute: 1,
    someOtherAttribute: 2
  }
}

Describe the value this feature would provide

This will allow people in my team's situation (already committed to flat list approach) to have top-level documentation of our events without changing our payload format. This will allow us to more easily convey when consumers should expect the event to be published. Currently, this documentation lives in our API resource, since that's the only place we can put it, and it's not a great UX for consumers to look there.

Workaround

This is medium priority, because we can go with the second approach described above and copy every attribute from our reslang resource into the event payload. But that would force us to keep the attribute list in two places, and we'd run the risk them getting out of sync if we are careless when we update.