Partial Item Schema Support

[x-delfino]

AI Usage Disclosure: Claude Code Opus 4.6 was used in developing this PR

Apologies for raising this PR without opening an issue and discussing first

OpenAPI 3.2 introduced support for sequential and streaming data, including:

• Server-Sent Events: text/event-stream
• Sequential JSON:
  • JSON Lines: application/jsonl
  • JSON Sequences: application/json-seq
  • NDJSON: application/x-ndjson

This is done using the itemSchema field on the Media Type Object

Existing Support

Server

Nothing has been changed for the server implementation currently and I think all servers should be able to support streaming to clients

• http/std, chi & gorilla: http.Flusher should be implemented on the http.ResponseWriter so they can send then flush
• echo: can access the flusher from the echo context with http.NewResponseController(ctx.Response()).Flush() https://echo.labstack.com/docs/cookbook/sse
• gin: this is handled by *Context.Stream() with helpers available for SSE
• iris: can access the flusher with ctx.ResponseWriter().Flusher() https://iris-go.gitbook.io/iris/responses/sse#server-side-code-example
• fiber: uses fasthttp.StreamWriter as shown in https://github.com/gofiber/recipes/blob/master/sse/main.go

Client

Nothing has been changed on the client generation. The base client should be able to handle the events from *http.Response without further changes.

Changes

This PR includes the following changes, providing additional support for ItemSchema:

codegen/internal/operation.go:

• Added ItemSchema *SchemaDescriptor and IsSequential bool to RequestBodyDescriptor and ResponseContentDescriptor
• Added IsSequentialMediaType(contentType string) bool helper — recognises aforementioned sequential/streaming content types

codegen/internal/gather.go:

• Updated gatherFromMediaType() to also gather mt.ItemSchema when present

codegen/internal/configuration.go:

• Extended DefaultContentTypes() to include aforementioned sequential/streaming content types

codegen/internal/gather_operations.go:

• gatherResponse(): extracts mediaType.ItemSchema via schemaProxyToDescriptor(), sets IsSequential on ResponseContentDescriptor
• gatherRequestBodies(): same for RequestBodyDescriptor

In terms of changes to generated code, types for items described by itemSchema will now be generated. The other changes are there to allow extending client/server generation where needed

Outstanding

SimpleClient

The SimpleClient will currently ignore these operations and so corresponding methods will not be generated:

oapi-codegen-exp/experimental/codegen/internal/templates/files/client/simple.go.tmpl

Lines 39 to 40 in 71d4907

	{{- $simpleOp := isSimpleOperation . }}
	{{- if $simpleOp }}

oapi-codegen-exp/experimental/codegen/internal/clientgen.go

Lines 136 to 137 in 71d4907

	// The single content type must be JSON
	return success.Contents[0].IsJSON

Would you want support for this in the simple client?

Strict Server

Are there plans to implement strict server similar to the previous version? IsSequential and ItemSchema are available on the descriptors to help handle this

Client -> Server

Reading the spec, I think it technically supports itemSchema in a Media Type Object that's in a Request Body Object rather than a Response Object but I don't think that's a typical use case and isn't a use case specifically referenced in the documentation. If you don't want to support it, we can revert the changes on RequestBodyDescriptor

[mromaszewicz]

Thanks, I will look over this. I've not pushed it yet, but I'm 90% done with item schemas on my end as well. I'll see what you've done to see if anything is better and add you as a co-author if I borrow anything, deal? :)

[x-delfino]

awesome - thanks!