How to document websockets?

user_10339199 0
Viewed 1844

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.

grpc postman documentation rest websocket
2 Answers

tl;dr use AsyncAPI for it.

Here are some learning materials:

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.

user_20881670

I've been googling some time for a searching solution for documenting WebSockets, and my answer is some kind of disappointing - Postman, OpenAPI or RAML don't support WebSocket documentation. So the only rational way to document parts of software that are using WebSockets is to write technical documentation by hand.

Checked examples on bigger organizations like Slack and so on, and they use the same practices for documenting real-time sockets, just write technical documentation by hand, I don't know how good that solution is but basically it will work so it's fine.

user_103391990
Related