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..1e46a7b3858 100644 --- a/packages/openapi3/test/multipart.test.ts +++ b/packages/openapi3/test/multipart.test.ts @@ -1,9 +1,57 @@ +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( `