micronaut-projects / micronaut-projects/micronaut-openapi

Add support for HTTP Server Sent Events (SSE) in controller generation

Open
#2,643 0 comments 2 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

type: improvement
Dominant language
Java
Stars
114
Forks
121
Avg merge
2d 17h
Merged PRs (30d)
25

Description

### Feature description

# Description

The generator should add support for HTTP Server Sent Events using Micronaut's [`Event`](https://docs.micronaut.io/latest/guide/index.html#sse) API.

Given a valid OpenAPI schema, if a `text/event-stream` content type is encountered in a response definition during generation, the generator should:
1. Select the relevant output schema (as currently done for normal request-response content types) (🍐)
2. Generate a corresponding type `T`
3. Set `Publisher>>` as the return type of the generated controller method
4. Append `text/event-stream` to the list of content types inside the HTTP method annotation or via a `@Produces` annotation

(🍐) I don't know `micronaut-openapi`'s behavior in detail, but I suppose the library selects the schema associated to 200 HTTP status code.

## Additional notes

- The return type should be wrapped in a `Mono` or the method marked `suspend` if the corresponding generator options are enabled (consistent with the current generator behavior)
- Multiple HTTP response codes returning a `text/event-stream` should not have explicit support
- By default, we could also add a `@ExecuteOn(TaskExecutors.IO)` annotation and potentially make the executor controllable per-method via an extension (e.g. `x-executor: blocking|io|message_consumer|scheduled|virtual`, list from [here](https://docs.micronaut.io/latest/api/io/micronaut/scheduling/TaskExecutors.html))

## Example OpenAPI schema

```yaml
openapi: 3.0.1
info:
title: Unik
description: Unik API
version: "0.0"
paths:
/users/stream:
get:
operationId: streamNewUsers
responses:
200:
description: Successful response
content:
text/event-stream:
schema:
$ref: "#/components/schemas/User"
409:
description: Can't stream users
content:
application/json:
schema:
$ref: "#/components/schemas/ApiProblem"
components:
schemas:
User:
type: object
ApiProblem:
type: object
```

## Expected generated controller interface

```kotlin
import com.generated.api.User
import io.micronaut.http.sse.Event
import org.reactivestreams.Publisher

/* -- snip -- */

interface DefaultApi {
@Get("/users/stream")
@Produces("text/event-stream", "application/json")
suspend fun streamNewUsers(): Publisher>
}
```

Contributor guide

No contributing guide indexed for this repository

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by tracing the controller-generation path that handles response content types and the existing normal request-response schema selection. Compare its output with the Kotlin example in the issue. Done means a text/event-stream response generates Publisher>, preserves the relevant schema, adds the stream content type, and follows the existing Mono or suspend options.

Written by the indexing model from the issue text.

Assessment

Tech stack
java, kotlin, openapi
Domain
api, tooling
Issue type
Feature
Difficulty
4/5
Estimated time
3-5 days
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
48/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.