Guides

WebSocket endpoints

Model and test WebSocket APIs alongside HTTP — single spec, AsyncAPI export.

Updated

OpenAPI 3.x doesn’t natively model WebSocket APIs — that’s AsyncAPI’s domain. OpenAPI Studio lets you describe WebSocket endpoints inside the same spec using a small set of OpenAPI extensions (AsyncAPI-shaped, so export is one click).

Adding a WebSocket endpoint

  1. Add a path to your spec (e.g. /v1/stream).
  2. Toggle the new Protocol selector to WebSocket on the operation.
  3. The editor switches to the WebSocket-specific form.

WS endpoints render in the flow builder with a sky-blue WS badge so they’re distinguishable from HTTP at a glance.

Editing a WebSocket endpoint

The WebSocketEditor has four tabs:

  • Connection — full URL (ws:// or wss://), subprotocols, where auth is carried (header / query / subprotocol).
  • Send — message templates the client can send. Each has a name, content type, JSON Schema, and example.
  • Receive — message templates the server sends, same shape.
  • Bindings — idle timeout, ping interval, max payload size.

Send and receive templates feed the live executor and the AsyncAPI export.

Connecting and watching transport

The Run tab on a WebSocket endpoint opens a Connect & Watch panel:

  1. Pick a server, fill in any auth header, click Connect.
  2. Watch frames stream in chronologically, with ↑ (sent) and ↓ (received) arrows, timestamps, and sizes.
  3. Click any frame to inspect it. JSON payloads pretty-print and validate against your Receive templates.
  4. Send messages from the composer — pick a template, edit, hit Cmd/Ctrl Enter or click Send.
  5. Disconnect when done. Close codes and reasons are surfaced.

Sessions are bridged through our server (no CORS), and frames are streamed in both directions in real time.

Transcripts

Every session is captured for 7 days. Frame metadata (counts, sizes, close code) lives in the execution history; the full NDJSON transcript is stored in object storage and can be re-downloaded later.

AsyncAPI export

When at least one WebSocket endpoint is in your spec, an AsyncAPI button appears in the export panel. It generates an AsyncAPI 3.0 YAML document mapping:

  • x-channel → AsyncAPI channels
  • send / receive operations → AsyncAPI operations with action send / receive
  • message templates → components.messages
  • Servers (with http(s) coerced to ws(s)) → AsyncAPI servers

Hand the file to AsyncAPI codegen, AsyncAPI Studio, or any AsyncAPI-aware tool.

Validation

The editor validates WebSocket-specific rules inline:

  • URL must resolve (a ws/wss:// channel URL or a server is required).
  • At least one send or receive message template is recommended.
  • Message names must be non-empty.
  • Subprotocols must be unique.

Issues surface as an amber list above the tabs.