diff --git a/.chronus/changes/copilot-openapi-emitter-respect-return-type-doc-2026-7-28-13-0-55.md b/.chronus/changes/copilot-openapi-emitter-respect-return-type-doc-2026-7-28-13-0-55.md new file mode 100644 index 00000000000..f75bce60854 --- /dev/null +++ b/.chronus/changes/copilot-openapi-emitter-respect-return-type-doc-2026-7-28-13-0-55.md @@ -0,0 +1,7 @@ +--- +changeKind: fix +packages: + - "@typespec/http" +--- + +Respect docs on union variants used as HTTP responses \ No newline at end of file diff --git a/packages/http/src/responses.ts b/packages/http/src/responses.ts index 113962517dd..dfc2f920df7 100644 --- a/packages/http/src/responses.ts +++ b/packages/http/src/responses.ts @@ -78,7 +78,11 @@ function resolveResponseVariants( continue; } // Recursively resolve nested unions - const resolved = resolveResponseVariants(program, option.type, unionDescription); + const resolved = resolveResponseVariants( + program, + option.type, + getDoc(program, option) ?? unionDescription, + ); for (const variant of resolved) { if (isPlainResponseBody(program, variant.type)) { plainVariants.push(variant.type); diff --git a/packages/openapi3/test/response-descriptions.test.ts b/packages/openapi3/test/response-descriptions.test.ts index d00b686bbe1..bbfa05180a2 100644 --- a/packages/openapi3/test/response-descriptions.test.ts +++ b/packages/openapi3/test/response-descriptions.test.ts @@ -87,6 +87,22 @@ worksFor(supportedVersions, ({ openApiFor }) => { strictEqual(res.paths["/"].get.responses["409"].description, "Foo"); }); + it("uses union variant descriptions", async () => { + const res = await openApiFor( + ` + model PetCreated { @statusCode code: 201 } + model PetAccepted { @statusCode code: 202 } + union CreatedResponses { + @doc("Pet Created") created: PetCreated, + @doc("Pet Accepted") accepted: PetAccepted, + } + op created(): CreatedResponses; + `, + ); + strictEqual(res.paths["/"].get.responses["201"].description, "Pet Created"); + strictEqual(res.paths["/"].get.responses["202"].description, "Pet Accepted"); + }); + it("recursively expands deeply nested unions", async () => { const res = await openApiFor( `