How to document websocket events or callback in swagger

api websocket documentation swagger
Martin Ingvar Kofoed Jensen picture Martin Ingvar Kofoed Jensen · Dec 1, 2015 · Viewed 8k times · Source

I have a setup where it is possible to get some resource using standard REST and this is easy documented in swagger. The same resource is pushed to clients using websockets when it has changed, so clients does not have to do a pull on an interval basis.

But how can I document this in swagger? Is it even possible? If not, what other tool do you recommend for documenting both the REST api and the websocket part?

Answer

Italo Borssatto picture Italo Borssatto · Aug 14, 2017

OpenAPI 3 (aka Swagger 3) has an upgrade in the response formats where they added the concept of callbacks, which allow you to define a webhook. Take a look at this part of the documentation: response format.

In Swagger 2 what I use to do is to implement an API method that implements exactly the same I expect from a callback and I just reference it in the original method that waits the callback. So any consumer can at least see the format of message that I'm expecting from them, using the Swagger specification.

Related questions

No 'Access-Control-Allow-Origin' header is present on the requested resource—when trying to get data from a REST API

I'm trying to fetch some data from the REST API of HP Alm. It works pretty well with a small curl script - I get my data. Now doing that with JavaScript, fetch and ES6 (more or less) seems to …

Read More
How do I make calls to a REST API using C#?

This is the code I have so far: using System; using System.Collections.Generic; using System.Linq; using System.Text; using System; using System.Net.Http; using System.Web; using System.Net; using System.IO; namespace ConsoleProgram { public class Class1 { …

Read More
How do you set the Content-Type header for an HttpClient request?

I'm trying to set the Content-Type header of an HttpClient object as required by an API I am calling. I tried setting the Content-Type like below: using (var httpClient = new HttpClient()) { httpClient.BaseAddress = new Uri("http://example.com/"); httpClient.DefaultRequestHeaders.…

Read More