From 701d680b5211eba835c8c40fb36101a26b913223 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Fri, 28 Aug 2026 12:51:43 +0000
Subject: [PATCH 1/3] Initial plan


From 2807c8101b0e1d7c0c9553000e85d108200545d0 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Fri, 28 Aug 2026 13:00:44 +0000
Subject: [PATCH 2/3] fix(http): preserve response union variant docs

Co-authored-by: timotheeguerin <1031227+timotheeguerin@users.noreply.github.com>
---
 packages/http/src/responses.ts                   |  6 +++++-
 .../openapi3/test/response-descriptions.test.ts  | 16 ++++++++++++++++
 2 files changed, 21 insertions(+), 1 deletion(-)

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(
       `

From edb52b03ccaaee10270b483fbe2050be174990d5 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Fri, 28 Aug 2026 13:11:51 +0000
Subject: [PATCH 3/3] chore: add HTTP response docs changelog

Co-authored-by: timotheeguerin <1031227+timotheeguerin@users.noreply.github.com>
---
 ...pi-emitter-respect-return-type-doc-2026-7-28-13-0-55.md | 7 +++++++
 1 file changed, 7 insertions(+)
 create mode 100644 .chronus/changes/copilot-openapi-emitter-respect-return-type-doc-2026-7-28-13-0-55.md

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