feat(http): support documentation on union variants for response descriptions #8962
+79
−4
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
tellnes
force-pushed
the
named-unions-response-doc
branch
3 times, most recently
from
fb0cfd4 to
f6fa39f
Compare
Contributor
|
All changed packages have been documented.
Show changes
|
Member
|
/azp run typespec - pr tools |
|
Azure Pipelines successfully started running 1 pipeline(s). |
.chronus/changes/named-unions-response-doc-2025-10-10-16-34-57.md
Outdated
Show resolved
Hide resolved
Collaborator
|
You can try these changes here
|
tellnes
force-pushed
the
named-unions-response-doc
branch
2 times, most recently
from
fb1c184 to
d0d3f3f
Compare
tellnes
changed the title
tellnes
force-pushed
the
named-unions-response-doc
branch
from
d0d3f3f to
7378cf2
Compare
github-merge-queue bot
pushed a commit
that referenced
this pull request
Nov 13, 2025
…8961) 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. ---- 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.
…riptions 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: @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.
tellnes
force-pushed
the
named-unions-response-doc
branch
from
7378cf2 to
c6fc35e
Compare
commit: |
timotheeguerin
approved these changes
Nov 27, 2025
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.
feat(http): support documentation on union variants for response descriptions
Allows using
@docon unions to provide a unified description for allresponses 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:
The union's
@doctakes precedence over individual variant descriptions.For nested unions, the innermost union's
@doctakes precedence, allowingfine-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
@docis specified.This MR depends on #8961
The commit from that MR is included here since Github does not support
stacked MRs from forks.