dotnet / dotnet/aspnetcore

Support OpenAPI 3.2 itemSchema in ASP.NET Core OpenAPI generation

Open
#65,904 3 comments 1 reaction 0 assignees View on GitHub
area-minimal feature-openapi
Dominant language
C#
Stars
38.4k
Forks
10.9k
Avg merge
2d 6h
Merged PRs (30d)
290

Description

### Is there an existing issue for this?

- [x] I have searched the existing issues

### Is your feature request related to a problem? Please describe the problem.

ASP.NET Core currently does not expose or generate the `itemSchema` property introduced in OpenAPI 3.2 for media types.

Although `itemSchema` is already supported in Microsoft.OpenApi (OpenAPI.NET), there is no way to utilize it through ASP.NET Core's OpenAPI generation pipeline.

This becomes a limitation when describing request and response bodies that require per-item schema definitions (e.g., streaming or sequence-based payloads such as NDJSON, or multipart scenarios), where `schema` alone is insufficient.

This limitation affects both request and response scenarios, since media types are used in both directions in OpenAPI definitions.

As a result, ASP.NET Core cannot fully represent OpenAPI 3.2 media type capabilities.

### Describe the solution you'd like

Add support for emitting and configuring `itemSchema` in OpenAPI documents generated by ASP.NET Core.

Ideally:
- Allow developers to specify `itemSchema` via attributes or configuration
- Ensure the OpenAPI generator maps collection-based or multipart scenarios correctly to `itemSchema`
- Align ASP.NET Core OpenAPI output with OpenAPI 3.2 specification support already present in OpenAPI.NET

### Additional context

- OpenAPI.NET already includes `itemSchema` in `OpenApiMediaType`
- However, ASP.NET Core does not expose this capability

One practical example where this becomes an issue is libraries that handle streaming or sequence-based payloads (e.g., NDJSON or chunked responses). In such cases, describing per-item schemas is important, but currently not possible.

For example, in a custom library (Juner.AspNetCore.Sequence), this limitation prevents accurate OpenAPI descriptions of sequence-based responses.

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.