Let readers try WebSocket channels

The Try it button on a WebSocket channel opens Replay. In Replay, readers connect from their browser straight to your server, send the channel's messages, and read the replies. Because the browser connects directly, the connection works only when your description, your server, and your project allow it.

A channel displays the Try it button when your description says that the channel uses WebSocket:

• One of the channel's servers uses the ws or wss protocol. A channel that lists no servers uses every server of the description.
• The description declares no servers, and the channel has a ws binding. Readers then enter the server address in Replay.

The channel also needs at least one message with a payload or an example. Other channels, such as Kafka or AMQP channels, have no Try it button.

The following example declares a WebSocket channel in a description without servers:

channels:
  liveOrders:
    address: /orders/live
    bindings:
      ws: {}

• Declare the server with protocol: wss. Browsers block ws:// connections from docs pages served over HTTPS.
• If your server checks the Origin header, allow your project's domain.
• If your project sends a Content-Security-Policy header, add your server to its connect-src directive.

In a browser, Replay can set only the address and the subprotocols of a WebSocket connection. It cannot add other headers, cookies, or client certificates. Declare the credential in one of these forms, and list it in the security of your wss server or of the channel's operations:

• An API key in the query: a security scheme with type: httpApiKey and in: query.
• A token sent as a subprotocol: a security scheme with type: httpApiKey, in: header, and name: Sec-WebSocket-Protocol. The browser sends subprotocols in the Sec-WebSocket-Protocol header.

The following example lets readers connect with either credential:

servers:
  production:
    host: live.cafe.example.com
    protocol: wss
    security:
      - $ref: '#/components/securitySchemes/queryKey'
      - $ref: '#/components/securitySchemes/subprotocolToken'
components:
  securitySchemes:
    queryKey:
      type: httpApiKey
      in: query
      name: api_key
    subprotocolToken:
      type: httpApiKey
      in: header
      name: Sec-WebSocket-Protocol

Replay fills its message editor with the first example of the message the reader picks. Without an example, Replay generates a payload from the message schema. Add an example with a payload to each message that readers send, so they start from realistic values.

• On every channel: set the hideReplay option under asyncapi in redocly.yaml.
• On one channel: add the x-hideReplay extension to the channel.

• hideReplay for AsyncAPI - Hide the Try it button on every channel
• x-hideReplay for AsyncAPI - Hide the Try it button on one channel
• Response headers - Set a Content-Security-Policy header for your project
• Add AsyncAPI descriptions - Add AsyncAPI reference documentation to your project