AsyncAPI Rendering Path designed
Event reference rendering should not be treated as a side effect of REST API rendering. AsyncAPI, NATS subjects, event taxonomy, and consumer/runbook context need their own portal path.
Decision
Keep the synced AsyncAPI artifact as the source, then add event reference rendering in two stages:
- Portal-native event guide and stream map first.
- Generated AsyncAPI/event reference route once the renderer is selected.
Rendering Model
Reference Requirements
| Area | Requirement |
|---|---|
| Contract authority | Event shapes come from AsyncAPI, not hand-written payload copies |
| Envelope clarity | Every event page explains event ID, type, version, correlation ID, timestamp, and payload |
| Subject mapping | NATS subjects and streams remain visible beside event names |
| Consumer posture | Consumers need idempotency, retry, duplicate delivery, and DLQ expectations |
| Examples | Examples should be generated or curated from contract-backed payloads |
| Publication tracks | Public/partner event docs may expose selected events; internal docs keep complete stream operations |
Candidate Tooling
| Option | Fit |
|---|---|
| AsyncAPI Generator / React components | Strong candidate if we want generated event docs from AsyncAPI |
| Portal-native generated MDX | Good if we need tight control over NATS/runbook context |
| Static artifact only | Safe baseline, already implemented, insufficient long term |
| Force into REST renderer | Poor fit; event consumers need different context |
Next Step
Create a generated event-reference pilot route after the REST reference pilot is stable. Keep Event Streams as the human guide and link the generated route from Contract Artifacts.