openapi3 - fix bug where union-level docs were applied to members

.chronus/changes/inv-openapi3-circ-ref-2024-6-19-13-33-42.md

@@ -0,0 +1,7 @@
+---
+changeKind: fix
+packages:
+  - "@typespec/openapi3"
+---
+
+Fixes bug where union documentation was being applied to each union member in emitted output.

packages/openapi3/src/schema-emitter.ts

@@ -523,14 +523,16 @@ export class OpenAPI3SchemaEmitter extends TypeEmitter<
 
     const wrapWithObjectBuilder = (
       schemaMember: { schema: any; type: Type | null },
-      { applyNullable }: { applyNullable: boolean }
+      { mergeUnionWideConstraints }: { mergeUnionWideConstraints: boolean }
     ): ObjectBuilder<OpenAPI3Schema> => {
       // we can just return the single schema member after applying nullable
       const schema = schemaMember.schema;
       const type = schemaMember.type;
-      const additionalProps: Partial<OpenAPI3Schema> = this.#applyConstraints(union, {});
+      const additionalProps: Partial<OpenAPI3Schema> = mergeUnionWideConstraints
+        ? this.#applyConstraints(union, {})
+        : {};
 
-      if (applyNullable && nullable) {
+      if (mergeUnionWideConstraints && nullable) {
         additionalProps.nullable = true;
       }
 
@@ -573,11 +575,13 @@ export class OpenAPI3SchemaEmitter extends TypeEmitter<
     }
 
     if (schemaMembers.length === 1) {
-      return wrapWithObjectBuilder(schemaMembers[0], { applyNullable: true });
+      return wrapWithObjectBuilder(schemaMembers[0], { mergeUnionWideConstraints: true });
     }
 
     const schema: OpenAPI3Schema = {
-      [ofType]: schemaMembers.map((m) => wrapWithObjectBuilder(m, { applyNullable: false })),
+      [ofType]: schemaMembers.map((m) =>
+        wrapWithObjectBuilder(m, { mergeUnionWideConstraints: false })
+      ),
     };
 
     if (nullable) {

packages/openapi3/test/union-schema.test.ts

@@ -441,4 +441,24 @@ describe("openapi3: union type", () => {
     strictEqual(res.schemas.Foo.title, "FooUnion");
     strictEqual(res.schemas.Bar.title, "BarUnion");
   });
+
+  it("does not duplicate top-level description on union members", async () => {
+    const res = await oapiForModel(
+      "Foo",
+      `
+      @doc("The possible types of things")
+      union Foo {
+        string,
+
+        bar: "bar",
+        buzz: "buzz",
+      }`
+    );
+
+    strictEqual(res.schemas.Foo.description, "The possible types of things");
+    strictEqual(res.schemas.Foo.anyOf.length, 2);
+    for (const variant of res.schemas.Foo.anyOf) {
+      strictEqual(variant.description, undefined);
+    }
+  });
 });