micronaut-projects / micronaut-projects/micronaut-openapi
Add support for HTTP Server Sent Events (SSE) in controller generation
Nobody has claimed this yet.
- 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
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- 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