How to document websockets?

Currently, I'm working on a project where I using websockets, in my past projects where I've been using mostly RESTful standard that was simple to document using Postman or Swagger, but actually I've spotted issue because Postman and Swagger seem to don't support WebSockets.

My question is how you're documenting WebSockets? Any information will be helpful but I'm mostly seeking some tool that will allow me to store documentation and share it with others.

The only thing that I've found is https://hoppscotch.io/

UPDATE 2022: Postman introduced new tools for documenting APIs including websockets and grpc what exactly resolves this issue and provides great tools to document further APIs.

Solution 1:

tl;dr use AsyncAPI for it.

Here are some learning materials:

• WebSocket, Shrek, and AsyncAPI - An Opinionated Intro
• Creating AsyncAPI for WebSocket API - Step by Step
• From API-First to Code Generation - A WebSocket Use Case

Official example of AsyncAPI document for real WebSocket API: Gemini API. For preview in AsyncAPI Playground click here.

YouTube presentation from EDASummit called An Opinionated Intro to AsyncAPI with WebSocket and Shrek and live stream that covers the first two articles mentioned above.