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:
  @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.

Author: tellnes

.chronus/changes/named-unions-response-doc-2025-10-10-16-34-57.md

@@ -0,0 +1,7 @@
+---
+changeKind: feature
+packages:
+  - "@typespec/http"
+---
+
+support documentation on union variants for response descriptions

packages/http/src/responses.ts

@@ -34,15 +34,24 @@ export function getResponsesForOperation(
   const responses = new ResponseIndex();
   const tk = $(program);
   if (tk.union.is(responseType) && !tk.union.getDiscriminatedUnion(responseType)) {
+    // Check if the union itself has a @doc to use as the response description
+    const unionDescription = getDoc(program, responseType);
     for (const option of responseType.variants.values()) {
       if (isNullType(option.type)) {
         // TODO how should we treat this? https://github.com/microsoft/typespec/issues/356
         continue;
       }
-      processResponseType(program, diagnostics, operation, responses, option.type);
+      processResponseType(
+        program,
+        diagnostics,
+        operation,
+        responses,
+        option.type,
+        unionDescription,
+      );
     }
   } else {
-    processResponseType(program, diagnostics, operation, responses, responseType);
+    processResponseType(program, diagnostics, operation, responses, responseType, undefined);
   }
 
   return diagnostics.wrap(responses.values());
@@ -81,6 +90,7 @@ function processResponseType(
   operation: Operation,
   responses: ResponseIndex,
   responseType: Type,
+  parentDescription?: string,
 ) {
   const tk = $(program);
 
@@ -89,11 +99,20 @@ function processResponseType(
   // or when unions are nested (e.g., a union variant is itself a union).
   // Each variant will be processed separately to extract its status codes and responses.
   if (tk.union.is(responseType) && !tk.union.getDiscriminatedUnion(responseType)) {
+    // Check if this nested union has its own @doc, otherwise inherit parent's description
+    const unionDescription = getDoc(program, responseType) ?? parentDescription;
     for (const option of responseType.variants.values()) {
       if (isNullType(option.type)) {
         continue;
       }
-      processResponseType(program, diagnostics, operation, responses, option.type);
+      processResponseType(
+        program,
+        diagnostics,
+        operation,
+        responses,
+        option.type,
+        unionDescription,
+      );
     }
     return;
   }
@@ -132,7 +151,14 @@ function processResponseType(
     const response: HttpOperationResponse = responses.get(statusCode) ?? {
       statusCodes: statusCode,
       type: responseType,
-      description: getResponseDescription(program, operation, responseType, statusCode, metadata),
+      description: getResponseDescription(
+        program,
+        operation,
+        responseType,
+        statusCode,
+        metadata,
+        parentDescription,
+      ),
       responses: [],
     };
 
@@ -223,7 +249,13 @@ function getResponseDescription(
   responseType: Type,
   statusCode: HttpStatusCodes[number],
   metadata: HttpProperty[],
+  parentDescription?: string,
 ): string | undefined {
+  // If a parent union provided a description, use that first
+  if (parentDescription) {
+    return parentDescription;
+  }
+
   // NOTE: If the response type is an envelope and not the same as the body
   // type, then use its @doc as the response description. However, if the
   // response type is the same as the body type, then use the default status

packages/openapi3/test/response-descriptions.test.ts

@@ -103,4 +103,40 @@ worksFor(supportedVersions, ({ openApiFor }) => {
     strictEqual(res.paths["/"].get.responses["401"].description, "Model B");
     strictEqual(res.paths["/"].get.responses["403"].description, "Model C");
   });
+
+  it("uses union's @doc when specified on the union itself", async () => {
+    const res = await openApiFor(
+      `
+      @doc("Foo model") model Foo { @statusCode _: 409 }
+      @doc("Bar model") model Bar { @statusCode _: 409 }
+      @doc("The resource conflicts with an existing resource")
+      union Conflict { Foo: Foo; Bar: Bar };
+      op read(): { @statusCode _: 200, content: string } | Conflict;
+      `,
+    );
+    strictEqual(res.paths["/"].get.responses["200"].description, "The request has succeeded.");
+    strictEqual(
+      res.paths["/"].get.responses["409"].description,
+      "The resource conflicts with an existing resource",
+    );
+  });
+
+  it("nested union's @doc takes precedence over parent union's @doc", async () => {
+    const res = await openApiFor(
+      `
+      @doc("Model A") model A { @statusCode _: 400 }
+      @doc("Model B") model B { @statusCode _: 401 }
+      @doc("Model C") model C { @statusCode _: 403 }
+      @doc("Inner authentication errors")
+      union Inner { A: A; B: B };
+      @doc("All error responses")
+      union Outer { inner: Inner; C: C };
+      op read(): { @statusCode _: 200, content: string } | Outer;
+      `,
+    );
+    strictEqual(res.paths["/"].get.responses["200"].description, "The request has succeeded.");
+    strictEqual(res.paths["/"].get.responses["400"].description, "Inner authentication errors");
+    strictEqual(res.paths["/"].get.responses["401"].description, "Inner authentication errors");
+    strictEqual(res.paths["/"].get.responses["403"].description, "All error responses");
+  });
 });