Preserve union variant docs in OpenAPI response descriptions

[Copilot]

OpenAPI response descriptions discarded @doc annotations on return-type union variants, falling back to generic status-code descriptions.

• Response resolution

  • Propagate each union variant’s documentation while flattening response unions.
  • Preserve existing union-level documentation fallback.

• Coverage

  • Verify variant-specific descriptions across OpenAPI 3.0, 3.1, and 3.2.

union CreatedResponses {
  @doc("Pet Created") created: PetCreated,
  @doc("Pet Accepted") accepted: PetAccepted,
}

This emits Pet Created and Pet Accepted for the corresponding response descriptions.

• Fixes Openapi emitter should respect return type variant doc on response #2383

[azure-pipelines]

Azure Pipelines:
Successfully started running 1 pipeline(s).
1 pipeline(s) were filtered out due to trigger conditions.
There may be pipelines that require an authorized user to comment /azp run to run.

[pkg-pr-new]

Open in StackBlitz

npm i https://pkg.pr.new/@typespec/http@11785

npm i https://pkg.pr.new/@typespec/openapi3@11785

commit: edb52b0

[Copilot]

Pull request overview

Fixes OpenAPI response description generation so that @doc applied to return-type union variants is preserved when unions are flattened into concrete HTTP responses (instead of falling back to generic status-code descriptions).

Changes:

• Propagate union variant documentation through resolveResponseVariants so each resolved response can carry the correct description.
• Add an OpenAPI emitter regression test asserting variant-specific descriptions for distinct status codes across supported OpenAPI versions.
• Add a Chronus changelog entry for the behavioral fix in @typespec/http.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated no comments.

File	Description
packages/openapi3/test/response-descriptions.test.ts	Adds coverage that union variant @doc values become the emitted OpenAPI response descriptions.
packages/http/src/responses.ts	Preserves per-variant documentation while flattening response unions by threading variant @doc into the resolved description.
.chronus/changes/copilot-openapi-emitter-respect-return-type-doc-2026-7-28-13-0-55.md	Records the fix as a @typespec/http changelog entry.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[azure-sdk-automation]

You can try these changes here

🛝 Playground	🌐 Website	🛝 VSCode Extension