Menu
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?
756
In OpenAPI 3 specs, you can define callbacks – asynchronous, out-of-band requests that your service will send to some other service in response to certain events. This helps you improve the workflow your API offers to clients.
A callback is an asynchronous API request that originates from the API server and is sent to the client in response to an earlier request sent by that client. APIs can use callbacks to signal an event of interest and share data related to that event.
Webhooks are user-defined HTTP callbacks. They are triggered by some event in a web application and can facilitate integrating different applications or third-party APIs, like Twilio.
Twilio uses HTTP callbacks (webhooks) to let your application know when events happen, such as receiving an SMS message or getting an incoming phone call. When the event occurs, Twilio makes an HTTP request (usually a POST or a GET ) to the URL you configured for the webhook.
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.
102
If you love us? You can donate to us via Paypal or buy me a coffee so we can maintain and grow! Thank you!
Donate Us With
