Raccomandazione su come documentare l'API Websocket

Question

Ho scritto un'API Websocket usando socket.io.

Diciamo che dopo aver stabilito la connessione il server attende un login -event con un carico utile come {username: String, password: String}.

Il server risponde quindi con gli eventi login:accept o login:deny.

Solo se l'accesso è riuscito, il server risponde a un evento tweets:get con un evento tweets (che ha una serie di tweet come payload).

Esiste un modo standardizzato per documentare API come questa? Hai qualche consiglio ed esperienza?

Answer 1

C'è AsyncApi node tool per creare definizioni leggibili dalla macchina, è molto simile allo swagger ma per le API asincrone e ci sono strumenti per generare HTML come AsyncApi docgen e widdershins.

È possibile costruire la documentazione utilizzando yaml o json, a titolo di esempio:

asyncapi: "1.0.0" 

topics: 
    "tweets:get": 
     publish: 
      $ref: "#/components/messages/getTweets" 
    tweets: 
     subscribe: 
      $ref: "#/components/messages/tweetsList" 

Dove topics = events, publish = emit, e subscribe = on in termini socket.io

dopo aver affermato che l'autenticazione tramite socket.io dipende principalmente dai token, l'utente invierà un token di autenticazione nello options.query al tempo di avvio della connessione e l'autenticazione del token nel back-end, è possibile disconnettere la connessione se l'autenticazione non è riuscita. Non c'è bisogno di login:accept o login:deny

const socket = io('http://localhost?token=abc'); 
// or 
const socket = io({ query: { token: 'cde' } });