fix(http,openapi3): support nested unions in operation return types #8961
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
tellnes
requested review from
AlitzelMendez,
bterlson,
chrisradek,
markcowl,
timotheeguerin and
witemple-msft
as code owners
Contributor
tellnes
force-pushed
the
named-unions-response-type
branch
from
5206b58 to
e3f3bda
Compare
Contributor
Author
|
@microsoft-github-policy-service agree |
tellnes
force-pushed
the
named-unions-response-type
branch
2 times, most recently
from
2af7c26 to
d1ff4cf
Compare
Member
|
/azp run typespec - pr tools |
|
Azure Pipelines successfully started running 1 pipeline(s). |
.chronus/changes/named-unions-response-type-2025-10-10-16-34-2.md
Outdated
Show resolved
Hide resolved
Collaborator
|
You can try these changes here
|
tellnes
force-pushed
the
named-unions-response-type
branch
from
d1ff4cf to
3cdcf40
Compare
tellnes
changed the title
Nested unions (e.g., `op read(): A | (B | C)` or using a named union
like `union Conflict { ... }`) were not being expanded recursively when
used as operation return types, causing responses to be missing from
the generated OpenAPI output.
This fix:
- Adds recursive union expansion in processResponseType() to handle
nested unions at any level
- Updates getResponses() to group responses by status code before
processing to properly handle cases where multiple union variants
map to the same status code
- Ensures response descriptions are taken from the first variant when
multiple variants share a status code
The most common case is named unions, but this also fixes any scenario
where unions are nested within other unions in the return type.
tellnes
force-pushed
the
named-unions-response-type
branch
from
3cdcf40 to
b89b5c7
Compare
timotheeguerin
approved these changes
Nov 13, 2025
github-merge-queue bot
pushed a commit
that referenced
this pull request
Nov 27, 2025
…riptions (#8962) feat(http): support documentation on union variants for response descriptions Allows using `@doc` on unions to provide a unified description for all responses in that union, regardless of individual variant descriptions. This gives users explicit control over response descriptions when multiple response types share the same status code. Example: ```typespec @doc("The resource conflicts with an existing resource") union Conflict { DuplicateName: DuplicateNameError; DuplicateId: DuplicateIdError; } op createResource(): Resource | Conflict; ``` The union's `@doc` takes precedence over individual variant descriptions. For nested unions, the innermost union's `@doc` takes precedence, allowing fine-grained control over different groups of responses. This provides explicit control for cases where the default behavior (using the first variant's description) is not sufficient. Future enhancements could include intelligent description combining when variants have different descriptions but no union `@doc` is specified. --- This MR depends on #8961 The commit from that MR is included here since Github does not support stacked MRs from forks.
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Nested unions (e.g.,
op read(): A | (B | C)or using a named unionlike
union Conflict { ... }) were not being expanded recursively whenused as operation return types, causing responses to be missing from
the generated OpenAPI output.
This fix:
nested unions at any level
processing to properly handle cases where multiple union variants
map to the same status code
multiple variants share a status code
The most common case is named unions, but this also fixes any scenario
where unions are nested within other unions in the return type.
The reasons for why I want this fixed is because I want to be able to control the description on responses when there is multiple responses on the same status code. See #8962 for details.