From 2bcd986550768c8a05ec220a1316fdcf6077b7ef Mon Sep 17 00:00:00 2001 From: Timothee Guerin Date: Wed, 11 Nov 2026 09:35:34 -0500 Subject: [PATCH 1/2] fix(openapi3): validate named multipart schema components --- ...pi3-component-naming-2026-10-6-11-13-33.md | 7 +++ packages/openapi3/src/openapi.ts | 19 ++++++- packages/openapi3/test/multipart.test.ts | 52 ++++++++++++++++++- 3 files changed, 76 insertions(+), 2 deletions(-) create mode 100644 .chronus/changes/feat-openapi3-component-naming-2026-10-6-11-13-33.md diff --git a/.chronus/changes/feat-openapi3-component-naming-2026-10-6-11-13-33.md b/.chronus/changes/feat-openapi3-component-naming-2026-10-6-11-13-33.md new file mode 100644 index 00000000000..2264bc11e37 --- /dev/null +++ b/.chronus/changes/feat-openapi3-component-naming-2026-10-6-11-13-33.md @@ -0,0 +1,7 @@ +--- +changeKind: fix +packages: + - "@typespec/openapi3" +--- + +Validate named multipart schema component keys and report duplicate keys consistently, including with the default naming strategy. diff --git a/packages/openapi3/src/openapi.ts b/packages/openapi3/src/openapi.ts index 8abec881c0d..872c6510f7d 100644 --- a/packages/openapi3/src/openapi.ts +++ b/packages/openapi3/src/openapi.ts @@ -77,6 +77,7 @@ import { } from "@typespec/http"; import { getStreamMetadata } from "@typespec/http/experimental"; import { + checkDuplicateTypeName, getExtensions, getExternalDocs, getOpenAPITypeName, @@ -347,6 +348,7 @@ function createOAPIEmitter( let visibilityUsage: VisibilityUsageTracker; let sseModule: SSEModule | undefined; let jsonSchemaModule: JsonSchemaModule | undefined; + let multipartSchemaTypes: Map; // Map model properties that represent shared parameters to their parameter // definition that will go in #/components/parameters. Inlined parameters do not go in @@ -508,6 +510,7 @@ function createOAPIEmitter( currentPath = root.paths; params = new Map(); + multipartSchemaTypes = new Map(); paramModels = new Set(); tagsUsedInOperations = new Set(); } @@ -1419,10 +1422,20 @@ function createOAPIEmitter( required: requiredProperties, }; - const name = + let name = "name" in body.type && body.type.name !== "" ? getOpenAPITypeName(program, body.type, typeNameOptions) : undefined; + if (name !== undefined) { + name = ensureValidComponentFixedFieldKey(program, body.type, name); + if (name) { + const existing = multipartSchemaTypes.get(name); + if (existing && existing !== body.type) { + checkDuplicateTypeName(program, body.type, name, root.components!.schemas!); + } + multipartSchemaTypes.set(name, body.type); + } + } if (name) { root.components!.schemas![name] = schema; } @@ -1836,6 +1849,10 @@ function createOAPIEmitter( const schemas = root.components!.schemas!; const declarations = files[0].globalScope.declarations; for (const declaration of declarations) { + const multipartType = multipartSchemaTypes.get(declaration.name); + if (multipartType) { + checkDuplicateTypeName(program, multipartType, declaration.name, schemas); + } schemas[declaration.name] = declaration.value as any; } } diff --git a/packages/openapi3/test/multipart.test.ts b/packages/openapi3/test/multipart.test.ts index 69b9ca33e93..b5f0127492c 100644 --- a/packages/openapi3/test/multipart.test.ts +++ b/packages/openapi3/test/multipart.test.ts @@ -1,9 +1,59 @@ +import { expectDiagnostics } from "@typespec/compiler/testing"; import { deepStrictEqual } from "assert"; import { describe, expect, it } from "vitest"; import type { OpenAPI3Encoding, OpenAPI3Schema, OpenAPISchema3_1 } from "../src/types.js"; import { supportedVersions, worksFor } from "./works-for.js"; -worksFor(supportedVersions, ({ openApiFor }) => { +worksFor(supportedVersions, ({ openApiFor, diagnoseOpenApiFor, emitOpenApiWithDiagnostics }) => { + it("validates multipart keys before creating references", async () => { + const [doc, diagnostics] = await emitOpenApiWithDiagnostics(` + model \`Upload/Form\` { name: HttpPart; } + op upload(@multipartBody body: \`Upload/Form\`): void; + `); + expectDiagnostics(diagnostics, [ + { + code: "@typespec/openapi3/invalid-component-fixed-field-key", + }, + ]); + expect(Object.keys(doc.components!.schemas!)).toEqual(["Upload_Form"]); + expect(doc.paths["/"].post!.requestBody).toMatchObject({ + content: { "multipart/form-data": { schema: { $ref: "#/components/schemas/Upload_Form" } } }, + }); + }); + + it("reports duplicate multipart keys", async () => { + const diagnostics = await diagnoseOpenApiFor(` + @friendlyName("UploadForm") model First { a: HttpPart; } + @friendlyName("UploadForm") model Second { b: HttpPart; } + @route("/a") op first(@multipartBody body: First): void; + @route("/b") op second(@multipartBody body: Second): void; + `); + expectDiagnostics(diagnostics, [{ code: "@typespec/openapi/duplicate-type-name" }]); + }); + + it("reports collisions between multipart and regular schemas", async () => { + const diagnostics = await diagnoseOpenApiFor(` + @friendlyName("UploadForm") model Upload { name: HttpPart; } + model UploadForm { value: string; } + op upload(@multipartBody body: Upload): UploadForm; + `); + expectDiagnostics(diagnostics, [{ code: "@typespec/openapi/duplicate-type-name" }]); + }); + + it("allows repeated references to the same named multipart body", async () => { + const doc = await openApiFor(` + model UploadForm { name: HttpPart; } + @route("/a") op first(@multipartBody body: UploadForm): void; + @route("/b") op second(@multipartBody body: UploadForm): void; + `); + expect(Object.keys(doc.components.schemas)).toEqual(["UploadForm"]); + for (const path of ["/a", "/b"]) { + expect(doc.paths[path].post.requestBody.content["multipart/form-data"].schema).toEqual({ + $ref: "#/components/schemas/UploadForm", + }); + } + }); + it("create dedicated model for multipart", async () => { const res = await openApiFor( ` From 79f8083264717d9ad845a8d7cfd876e35c8e9491 Mon Sep 17 00:00:00 2001 From: Timothee Guerin Date: Thu, 12 Nov 2026 09:31:02 -0500 Subject: [PATCH 2/2] test(openapi3): use object expectations for single diagnostics --- packages/openapi3/test/multipart.test.ts | 12 +++++------- 1 file changed, 5 insertions(+), 7 deletions(-) diff --git a/packages/openapi3/test/multipart.test.ts b/packages/openapi3/test/multipart.test.ts index b5f0127492c..1e46a7b3858 100644 --- a/packages/openapi3/test/multipart.test.ts +++ b/packages/openapi3/test/multipart.test.ts @@ -10,11 +10,9 @@ worksFor(supportedVersions, ({ openApiFor, diagnoseOpenApiFor, emitOpenApiWithDi model \`Upload/Form\` { name: HttpPart; } op upload(@multipartBody body: \`Upload/Form\`): void; `); - expectDiagnostics(diagnostics, [ - { - code: "@typespec/openapi3/invalid-component-fixed-field-key", - }, - ]); + expectDiagnostics(diagnostics, { + code: "@typespec/openapi3/invalid-component-fixed-field-key", + }); expect(Object.keys(doc.components!.schemas!)).toEqual(["Upload_Form"]); expect(doc.paths["/"].post!.requestBody).toMatchObject({ content: { "multipart/form-data": { schema: { $ref: "#/components/schemas/Upload_Form" } } }, @@ -28,7 +26,7 @@ worksFor(supportedVersions, ({ openApiFor, diagnoseOpenApiFor, emitOpenApiWithDi @route("/a") op first(@multipartBody body: First): void; @route("/b") op second(@multipartBody body: Second): void; `); - expectDiagnostics(diagnostics, [{ code: "@typespec/openapi/duplicate-type-name" }]); + expectDiagnostics(diagnostics, { code: "@typespec/openapi/duplicate-type-name" }); }); it("reports collisions between multipart and regular schemas", async () => { @@ -37,7 +35,7 @@ worksFor(supportedVersions, ({ openApiFor, diagnoseOpenApiFor, emitOpenApiWithDi model UploadForm { value: string; } op upload(@multipartBody body: Upload): UploadForm; `); - expectDiagnostics(diagnostics, [{ code: "@typespec/openapi/duplicate-type-name" }]); + expectDiagnostics(diagnostics, { code: "@typespec/openapi/duplicate-type-name" }); }); it("allows repeated references to the same named multipart body", async () => {