SSE Support

[JohannesHepp]

Hey,

ktor 3.0.0 introduces support for SSE. We already use this feature. We also want to automatically add these endpoints to our open API spec. It would be great if you could add support for SSE to the open API spec for your library :)

[SMILEY4]

Hi, sorry for the late response.

I'm not sure if openapi is a good fit for documenting this type of communication. Do you have an idea or suugestion on how this could look like in swagger?

[king-phyte]

@JohannesHepp If it is merely about discovery, I think the package already supports that. Here is an example and the equivalent Swagger UI displayed

routing {
        sse("/server-sent-events/som") {
            repeat(1000) {
                send(ServerSentEvent("e203-2032"))
                delay(1000)
            }
        }
    }

@SMILEY4 I think we can add an extension function like we do got get, post, etc., for sse that allows one to descibe the requests and responses. That would help document it manually, like define security schemes and all other OpenAPI definitions we already have. For example, look at the code below and the equivalent Swagger UI, which is perfectly valid in Ktor:

routing {
        authenticate("user-jwt") {
            sse("/server-sent-events") {
                repeat(1000) {
                    val principal = call.principal<String>()
                    send(ServerSentEvent("Principal $principal"))
                    delay(1000)
                }
            }
        }

There is no way to add a security scheme to the above, so in Swagger, it appears like

Notice there is no padlock icon beside the route.

If we modified it to become like

routing {
        authenticate("user-jwt") {
            sse("/server-sent-events", {
            securitySchemeNames("User")
        }) {
                repeat(1000) {
                    val principal = call.principal<String>()
                    send(ServerSentEvent("Principal $principal"))
                    delay(1000)
                }
            }
        }

one would be able to get something like

Now notice the padlock icon, response definition and all

[JohannesHepp]

Yes the target would be to add some basic documentation like the correct tag, securitySchema,...

[SMILEY4]

ok yeah, i think that would be the way to go too or at least be a good first step and wouldn't require many changes