Spec Editor & Recording

Spec Editor & Recording

Beta — spec editing and traffic recording are new and not yet fully stable. The editor can behave oddly here and there, and a generated channel may be incomplete or get a detail wrong, so review what comes out. Your saved specs are safe: nothing is written to the active spec until you save a version.

Open any spec from the AsyncAPI Manager to get a full editor: a visual editor, the raw YAML, a traffic recorder that writes channels for you, and a version history with diffs.

You do not need an existing spec to start. Record traffic on a server, generate channels from what was captured, and you have a first draft of a specification for a system nobody documented.

Visual Editor (beta)

The Visual Editor tab edits the spec as a form instead of as text.

  • Document — title, version, default content type, description, and the servers block (host, pathname, protocol, protocol version, server bindings).
  • Channels — a resizable, collapsible rail listing every channel. Add, rename, or remove channels; select one to edit it.
  • Channel detail — address, description, operation, and channel bindings.
  • Message payload schema — every field with its type, format, enum values, required flag, and an optional description. Nested objects and arrays are edited in place.
  • Message headers schema — the same editor for headers.
  • Bindings — protocol bindings for the server, channel, operation, and message, with the fields for the protocol you pick.

Nothing is written to the active spec until you save a version, so you can experiment freely.

YAML Source (beta)

The YAML Source tab shows the same spec as text. Edits reparse automatically and flow back into the visual editor, so you can switch between the two at any point. Parse errors are reported inline instead of overwriting your work.

Recording (beta)

The Recording tab captures live traffic on the connected server and turns it into spec channels.

  1. Click Start recording. Every queue and topic on the server is recorded at once — no queue has to be open first.
  2. Let your system run. The status line shows the message count, how many routes across how many vhosts are being watched, and the safety cut-off.
  3. Click Stop when you have enough traffic.

Recording is read-only with respect to your broker: the real queues and their consumers are never touched, and no message is consumed away from its normal destination.

Recordings run until you stop them, with a safety cut-off after 24 hours so a forgotten session cannot run indefinitely. Sessions are kept per server and listed under Sessions; delete one when you no longer need it.

Generating channels

Under Captured channels you get one row per channel that was seen, with the number of samples collected. Click Generate on a row and HZN Queue Console infers a channel from those samples:

  • Payload schema with field types, formats, and enum values where the samples agree
  • Required fields, based on which fields appeared in every sample
  • Header schema, with broker delivery headers (x-death, x-delivery-count, _AMQ_*, JMSXDeliveryCount, …) left out — they describe one message’s journey, not the contract
  • Up to three recorded payloads as examples
  • A protocol binding for the exchange or destination the messages came from

A recording only ever observes messages arriving, so every generated operation is written as receive and flagged for you to verify. Inference is a starting point — review the types, tighten the enums, and add the descriptions only a human knows.

Regenerating a channel that already exists

Generate the same channel again after a later recording and the results are merged rather than overwritten:

  • Fields the spec did not have yet are added automatically
  • A field whose inferred type conflicts with what the spec already says is raised as a conflict, defaulting to keep existing — a machine guess never silently overwrites a human correction

History

The History tab lists every saved version of the spec, with the change that produced it and a diff against the previous version. Your unsaved edits show up as a Unsaved row so you can see exactly what you changed before saving.

  • Save Version stores the current working copy as a new version.
  • Active marks the version the queues and message validation actually use. Any saved version can take over with Make active — newer or older.
  • Each version can be downloaded as YAML or exported as a PDF document.

Planned: Git-backed versioning

Version history is stored locally today. Git-backed versioning — specs living in a repository next to the code they describe, with saves as commits — is on the roadmap. No release date yet.

Exporting

From the editor header:

  • Download writes the working spec to a .yaml file.
  • PDF renders the spec as printable API documentation, with the channels, message schemas, and bindings laid out per channel. The desktop app saves the PDF directly; in the browser it opens the printable document, which you save as PDF from the print dialog.