Swagger for Server Sent Events

[bmeck]

It would be nice if Swagger supported Server Sent Events. Which is a Uni-directional alternative for streaming content. This still would fall within REST to my knowledge (in particular due to last seen ID). A more concrete example can be seen at HTML5Rocks

semi-related : #55

[giowe]

@twhittock do you have something I can see to share ?

[shalberd]

@philsturgeon this is very disappointing and probably more of a communication- and approach problem. We, too, are using Server Sent Events. It is a clear part of http and API frameworks. The facts that it cannot be described in OpenAPI is deplorable. Then again, I just saw that something as basic as mTLS authentication mentioning (has been around forever) was only recently added as a field to SecuritySpec, so maybe I am expecting too much of OpenAPI spec. Will explore asyncAPI for Server Sent Events. It's a pity two different frameworks are necessary for in our case one API set.

[jroper]

@shalberd Using words like "deplorable" and "disappointing" is not the way to engage in an open source community. Please adjust your tone. @philsturgeon has invited anyone that wants to take the lead on putting this into the spec to join the weekly calls and do so. That includes you. Open source projects only work when community members that need features step up and engage to help provide those features. When you tell an open source project they are disappointing and deplorable for not adding a feature that they are happy to accept from a contributor, but don't volunteer to contribute yourself, you're actually pointing the finger at yourself, calling yourself disappointing and deplorable, since you're unwilling to do the work yourself.

[hasufell]

I think the signals from the maintainers of this project are not too clear. First off: this ticket has been closed as "completed". Why? Where's the "call for help" exactly?

[jroper]

It was not closed as "completed". The GitHub close reason feature went live in May 2022, with the preview starting for a few projects in March 2022. This was closed in February 2022. Completed is just the default reason. All issues that were closed prior to when the close reasons feature was added to GitHub have the reason of completed. For example, this issue from 2014 was also closed as "completed", 8 years prior to the ability to specify a close reason in GitHub.

As for the calls for help, just read through the comment history. Here's one, here's another and here's yet another.

I'm not part of the OpenAPI project, but I have led the development of multiple open source projects, and been very involved in several specification style projects like this. Looking over this issue, honestly, there's not a lot of serious interest in it. It takes you 2 minutes to write a comment saying you want this feature. That's not serious interest. Serious interest means submitting serious proposals, attending meetings where you sell those proposals, talking to multiple stakeholders in the project to understand what the different concerns are and addressing that. No one's doing that.

The OpenAPI spec we have today has been built off the backs of that kind of engagement for a decade. It's hard work, working with many different stakeholders all having their different opinions, going back and forth, coming up with solutions, reworking, reworking, reworking, incorporating lots of different feedback. And the result is that we have a quality spec that we all benefit from. People commenting on an issue saying this feature is important, that's just noise. People just turning up to one call and stating their pet feature, that's just noise too. This kind of half-hearted engagement happens a lot, but helps nothing. That's probably why the maintainers have closed this issue. Unless there's someone out there that is willing to do the many hours of work of leading this feature and getting it into the spec, no one can claim that it's important enough to be in the spec.

[hasufell]

@jroper I'm maintaining popular open source projects as well. I know how things work. There was no call for help here.

A call for help is when maintainers say "yeah, great idea, we need your help" or "important topic, let's discuss this asap".

As a maintainer, it's easy to get burned out and dismissive, because people are mostly just complaining. But you have to understand that you're hoping for someone else to potentially dedicate their free time to your project.

Small things can make a difference here. E.g. the issue has not been reopened. That in itself is a signal to potential contributors, whether that was intended or not.

[jroper]

Disagree. The maintainers have yet to be convinced of the importance of this issue, that's very clear from the comments they've made. They're not hoping for anyone to dedicate their free time to do this because they don't think it's important enough. But they have invited us to convince them otherwise. The fact that no one has done the work to show that has given them their answer. Until someone does, I don't see why they would reopen the issue.

[hasufell]

@jroper then don't be surprised when people express their frustration due to the lack of interest and engagement of the maintainers.

I'm maintaining a spec myself. And I encourage contributors to write even radical proposals, while being very upfront with the expectations: most of them will likely not be accepted. But it's good to have them anyway.

At any rate, I think most of us here lost interest in contributing.

[philsturgeon]

As I’ve said several times in this thread (but it’s been buried under lots of long replies), if you’re interested in this topic please join a weekly call and take the lead on making it happen.

I’m not really involved right now, busy running a climate charity unpaid, but as far as I know there’s nobody on the OpenAPI team who’s being paid to work on things you want. You can work on things you want, if you want.

Alternatively I am available for hire. If you’d like to put me on a retainer I can pioneer efforts to get this change discussed. My rate is $200/hr.

Otherwise it’s on you. Good luck!

[olawalejuwonm]

Is there any resolution as regards this? Will AsyncAPI be combined to OpenAPI so we can have server side event documented with it?

[nikojpapa]

Here is an example of a way I did it back in 2020. This was based off of v4.3.1. I don't remember exactly what I did, so I just remade, in a new repo, the relevant changes to the files that I think were pertinent. I think there is a similar structure in the latest version, so this can likely be adapted as needed.

This is using the new SSE in the typescript-fetch language, but you can change the mustache file that is relevant to you.

https://github.com/nikojpapa/openapi-generator/compare/003165c2c2..03081c9

You would then set the response in the API definition as something like the following:

  responses:
    "200":
      description: success
      content:
        text/event-stream:
          schema:
            $ref: "..."

[ihakh]

I used it to update the live chart so in my case the data has a fix structure and api can promise to have a fix structure

[dsinghvi]

For folks stumbling on this issue, Fern supports server sent events via extensions (https://buildwithfern.com/learn/api-definition/openapi/endpoints/sse)

[olawalejuwonm]

How can I use it for testing websocket / documenting it

On Sun, 15 Sept 2024, 19:17 Deep Singhvi, @.***> wrote:

For folks stumbling on this issue, Fern supports server sent events via extensions ( https://buildwithfern.com/learn/api-definition/openapi/endpoints/sse)

— Reply to this email directly, view it on GitHub https://github.com/OAI/OpenAPI-Specification/issues/396#issuecomment-2351711587, or unsubscribe https://github.com/notifications/unsubscribe-auth/AMSQ2BGUWNK6QQFASXOLTT3ZWXFMFAVCNFSM4BIWCKG2U5DIOJSWCZC7NNSXTN2JONZXKZKDN5WW2ZLOOQ5TEMZVGE3TCMJVHA3Q . You are receiving this because you commented.Message ID: @.***>

[megretson]

Hi all,

This issue clearly became contentious based on the above thread, but I was wondering if someone could provide a current status on SSE tooling support? Is there some canonical way of describing SSE or plans to support SSE in the generators?

Thanks!