diff --git a/.chronus/changes/feat-openapi3-component-naming-2026-10-4-18-35-26.md b/.chronus/changes/feat-openapi3-component-naming-2026-10-4-18-35-26.md new file mode 100644 index 00000000000..98ea666239f --- /dev/null +++ b/.chronus/changes/feat-openapi3-component-naming-2026-10-4-18-35-26.md @@ -0,0 +1,15 @@ +--- +changeKind: feature +packages: + - "@typespec/openapi3" +--- + +Add `component-name-strategy` to control namespace qualification and segment separators for OpenAPI schema and reusable parameter keys. Existing defaults are unchanged. + +```yaml +options: + "@typespec/openapi3": + component-name-strategy: name-only +``` + +Use `name-only` to omit namespaces, or configure `{ kind: fqn, separator: "_" }` to change segment separators. Characters within identifiers and friendly names remain unchanged. Collisions after namespace changes are errors. \ No newline at end of file diff --git a/.chronus/changes/feat-openapi3-component-naming-2026-10-6-11-13-28.md b/.chronus/changes/feat-openapi3-component-naming-2026-10-6-11-13-28.md new file mode 100644 index 00000000000..0cd858cea93 --- /dev/null +++ b/.chronus/changes/feat-openapi3-component-naming-2026-10-6-11-13-28.md @@ -0,0 +1,7 @@ +--- +changeKind: internal +packages: + - "@typespec/openapi" +--- + +Share duplicate schema and parameter component key diagnostics while preserving existing parameter error messages. \ No newline at end of file diff --git a/packages/openapi/src/helpers.ts b/packages/openapi/src/helpers.ts index 9ca67cb2b41..72bdfcb218a 100644 --- a/packages/openapi/src/helpers.ts +++ b/packages/openapi/src/helpers.ts @@ -89,16 +89,19 @@ export function getOpenAPITypeName( * @param type Type with the name to check * @param name Name to check * @param existing Existing map of name + * @param messageId - Whether to report a duplicate type name or parameter key. */ export function checkDuplicateTypeName( program: Program, type: Type, name: string, existing: Record | undefined, + messageId: "default" | "parameter" = "default", ) { if (existing && existing[name]) { reportDiagnostic(program, { code: "duplicate-type-name", + messageId, format: { value: name, }, @@ -124,16 +127,7 @@ export function getParameterKey( key += `.${property.name}`; } - if (existingParams[key]) { - reportDiagnostic(program, { - code: "duplicate-type-name", - messageId: "parameter", - format: { - value: key, - }, - target: property, - }); - } + checkDuplicateTypeName(program, property, key, existingParams, "parameter"); return key; } diff --git a/packages/openapi3/README.md b/packages/openapi3/README.md index 91e60720cd5..038da779362 100644 --- a/packages/openapi3/README.md +++ b/packages/openapi3/README.md @@ -172,6 +172,25 @@ See https://github.com/OAI/OpenAPI-Specification/discussions/4622 for discussion | `kind` | `"parent-container" \| "fqn" \| "explicit-only"` | `"parent-container"` | Determines how to generate operation IDs when `@operationId` is not used.
Avaliable options are:
- `parent-container`: Uses the parent namespace and operation name to generate the ID.
- `fqn`: Uses the fully qualified name of the operation to generate the ID.
- `explicit-only`: Only use explicitly defined operation IDs. | | `separator` | `string` | | Separator used to join segment in the operation name. | +### `component-name-strategy` + +**Type:** `"fqn" | "name-only" | object { kind, separator }` + +**Options:** + +- `"fqn" | "name-only"` (default: `"fqn"`) + + Naming strategy for schema and reusable parameter component keys. + `fqn` preserves service-relative namespace qualification; `name-only` omits namespaces. + Friendly names override namespace qualification. Operation IDs and HTTP names are unchanged. + +- `object { kind, separator }` + +| Name | Type | Default | Description | +| ----------- | ---------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `kind` | `"fqn" \| "name-only"` | `"fqn"` | Naming strategy for schema and reusable parameter component keys.
`fqn` preserves service-relative namespace qualification; `name-only` omits namespaces.
Friendly names override namespace qualification. Operation IDs and HTTP names are unchanged. | +| `separator` | `string` | `"."` | Separator between namespace and parameter-property segments. May be empty. Does not replace punctuation within identifiers or friendly names. | + ### `enum-strategy` **Type:** `"default" | "annotated"` diff --git a/packages/openapi3/src/component-naming.ts b/packages/openapi3/src/component-naming.ts new file mode 100644 index 00000000000..6f801bad3e3 --- /dev/null +++ b/packages/openapi3/src/component-naming.ts @@ -0,0 +1,31 @@ +import type { Program, Type, TypeNameOptions } from "@typespec/compiler"; +import { getFriendlyName, getTypeName, isStdNamespace } from "@typespec/compiler"; +import type { ResolvedOpenAPI3EmitterOptions } from "./openapi.js"; + +export function getComponentTypeName( + program: Program, + type: Type, + typeNameOptions: TypeNameOptions, + options: ResolvedOpenAPI3EmitterOptions, +): string { + const strategy = options.componentNameStrategy; + const friendlyName = getFriendlyName(program, type); + const name = friendlyName ?? getTypeName(type, { ...typeNameOptions, nameOnly: true }); + let namespace = "namespace" in type ? type.namespace : undefined; + if ( + friendlyName !== undefined || + strategy?.kind === "name-only" || + ("expression" in type && type.expression) || + (namespace && isStdNamespace(namespace)) + ) { + return name; + } + + const segments = [name]; + while (namespace && namespace.name !== "") { + if (typeNameOptions.namespaceFilter && !typeNameOptions.namespaceFilter(namespace)) break; + segments.unshift(namespace.name); + namespace = namespace.namespace; + } + return segments.join(strategy?.separator ?? "."); +} diff --git a/packages/openapi3/src/lib.ts b/packages/openapi3/src/lib.ts index 0a13d99e4ef..a8cbd9d7c4e 100644 --- a/packages/openapi3/src/lib.ts +++ b/packages/openapi3/src/lib.ts @@ -9,6 +9,8 @@ export type OpenAPIVersion = "3.0.0" | "3.1.0" | "3.2.0"; export type ExperimentalParameterExamplesStrategy = "data" | "serialized"; /** Enum representation: a single `enum` schema or annotated `const` alternatives for OpenAPI 3.1 and later. */ export type EnumStrategy = "default" | "annotated"; +/** Namespace qualification for schema and reusable parameter component keys. */ +export type ComponentNameStrategy = "fqn" | "name-only"; /** User-supplied emitter configuration; omitted settings are normalized by `resolveOptions`. */ export interface OpenAPI3EmitterOptions { /** @@ -116,6 +118,22 @@ export interface OpenAPI3EmitterOptions { separator?: string; }; + /** + * Naming strategy for schema and reusable parameter component keys. + * `fqn` preserves current service-relative namespace qualification; `name-only` omits namespaces. + * Friendly names override namespace qualification. Separators join namespace and parameter-property + * segments, not punctuation within identifiers or friendly names. + * @default fqn + */ + "component-name-strategy"?: + | ComponentNameStrategy + | { + /** Namespace qualification strategy. */ + kind: ComponentNameStrategy; + /** Separator between namespace and parameter-property segments; defaults to `"."`. May be empty. */ + separator?: string; + }; + /** * How to emit TypeSpec enums. * @@ -150,6 +168,17 @@ const operationIdStrategySchema = { ].join("\n"), } as const; +const componentNameStrategySchema = { + type: "string", + enum: ["fqn", "name-only"], + default: "fqn", + description: [ + "Naming strategy for schema and reusable parameter component keys.", + "`fqn` preserves service-relative namespace qualification; `name-only` omits namespaces.", + "Friendly names override namespace qualification. Operation IDs and HTTP names are unchanged.", + ].join("\n"), +} as const; + const EmitterOptionsSchema: JSONSchemaType = { type: "object", additionalProperties: false, @@ -293,6 +322,26 @@ const EmitterOptionsSchema: JSONSchemaType = { }, ], } as any, + "component-name-strategy": { + oneOf: [ + componentNameStrategySchema, + { + type: "object", + additionalProperties: false, + properties: { + kind: componentNameStrategySchema, + separator: { + type: "string", + nullable: true, + default: ".", + description: + "Separator between namespace and parameter-property segments. May be empty. Does not replace punctuation within identifiers or friendly names.", + }, + }, + required: ["kind"], + }, + ], + } as any, "enum-strategy": { type: "string", enum: ["default", "annotated"], diff --git a/packages/openapi3/src/openapi.ts b/packages/openapi3/src/openapi.ts index 8abec881c0d..9ded9f552da 100644 --- a/packages/openapi3/src/openapi.ts +++ b/packages/openapi3/src/openapi.ts @@ -77,21 +77,23 @@ import { } from "@typespec/http"; import { getStreamMetadata } from "@typespec/http/experimental"; import { + checkDuplicateTypeName, getExtensions, getExternalDocs, getOpenAPITypeName, - getParameterKey, getTagsMetadata, isReadonlyProperty, shouldInline, } from "@typespec/openapi"; import { stringify } from "yaml"; +import { getComponentTypeName } from "./component-naming.js"; import { getRef } from "./decorators.js"; import type { OperationExamples } from "./examples.js"; import { getExampleOrExamples, resolveOperationExamples } from "./examples.js"; import type { JsonSchemaModule } from "./json-schema.js"; import { resolveJsonSchemaModule } from "./json-schema.js"; import type { + ComponentNameStrategy, EnumStrategy, FileType, OpenAPI3EmitterOptions, @@ -247,6 +249,7 @@ export function resolveOptions( } const specDir = openapiVersions.length > 1 ? "{openapi-version}" : ""; + const componentNameStrategy = resolvedOptions["component-name-strategy"] ?? "fqn"; return { fileTypes, newLine: resolvedOptions["new-line"], @@ -258,6 +261,14 @@ export function resolveOptions( sealObjectSchemas: resolvedOptions["seal-object-schemas"], parameterExamplesStrategy: resolvedOptions["experimental-parameter-examples"], operationIdStrategy: resolveOperationIdStrategy(resolvedOptions["operation-id-strategy"]), + componentNameStrategy: { + kind: + typeof componentNameStrategy === "string" + ? componentNameStrategy + : componentNameStrategy.kind, + separator: + typeof componentNameStrategy === "string" ? "." : (componentNameStrategy.separator ?? "."), + }, enumStrategy, }; } @@ -291,6 +302,13 @@ function resolveOperationIdDefaultStrategySeparator(strategy: OperationIdStrateg /** Normalized emitter settings returned by `resolveOptions`, before document-specific path interpolation. */ export interface ResolvedOpenAPI3EmitterOptions { + /** Component qualification; defaults to service-relative `"fqn"` with `"."` separators. */ + componentNameStrategy?: { + /** Whether to include service-relative namespaces. */ + kind: ComponentNameStrategy; + /** Separator between namespace and parameter-property segments. */ + separator: string; + }; /** Formats requested for each document; inferred from the output extension or defaulted to YAML when absent. */ fileTypes: FileType[]; /** Resolved output path template; includes an OpenAPI-version directory when multiple specification versions are requested. */ @@ -1421,7 +1439,7 @@ function createOAPIEmitter( const name = "name" in body.type && body.type.name !== "" - ? getOpenAPITypeName(program, body.type, typeNameOptions) + ? getComponentTypeName(program, body.type, typeNameOptions, options) : undefined; if (name) { root.components!.schemas![name] = schema; @@ -1806,14 +1824,18 @@ function createOAPIEmitter( function emitParameters() { for (const [property, param] of params) { - const key = getParameterKey( + const parent = property.model!; + const name = getComponentTypeName(program, parent, typeNameOptions, options); + const separator = options.componentNameStrategy?.separator ?? "."; + const key = parent.properties.size > 1 ? name + separator + property.name : name; + const validKey = ensureValidComponentFixedFieldKey(program, property, key); + checkDuplicateTypeName( program, property, - param, + validKey, root.components!.parameters!, - typeNameOptions, + "parameter", ); - const validKey = ensureValidComponentFixedFieldKey(program, property, key); root.components!.parameters![validKey] = { ...param }; for (const key of Object.keys(param)) { delete param[key]; diff --git a/packages/openapi3/src/schema-emitter.ts b/packages/openapi3/src/schema-emitter.ts index 111cac8b868..dc534999e96 100644 --- a/packages/openapi3/src/schema-emitter.ts +++ b/packages/openapi3/src/schema-emitter.ts @@ -66,11 +66,11 @@ import { checkDuplicateTypeName, getExtensions, getExternalDocs, - getOpenAPITypeName, isReadonlyProperty, shouldInline, } from "@typespec/openapi"; import { attachExtensions } from "./attach-extensions.js"; +import { getComponentTypeName } from "./component-naming.js"; import { getOneOf, getRef } from "./decorators.js"; import type { JsonSchemaModule } from "./json-schema.js"; import type { OpenAPI3EmitterOptions } from "./lib.js"; @@ -258,7 +258,7 @@ export class OpenAPI3SchemaEmitterBase< ); } - const baseName = getOpenAPITypeName(program, model, this.#typeNameOptions()); + const baseName = getComponentTypeName(program, model, this.#typeNameOptions(), this._options); const isMultipart = this.getContentType().startsWith("multipart/"); const name = isMultipart ? baseName + "MultiPart" : baseName; @@ -308,7 +308,14 @@ export class OpenAPI3SchemaEmitterBase< } modelInstantiation(model: Model, name: string | undefined): EmitterOutput> { - name = name ?? getOpenAPITypeName(this.emitter.getProgram(), model, this.#typeNameOptions()); + name = + name ?? + getComponentTypeName( + this.emitter.getProgram(), + model, + this.#typeNameOptions(), + this._options, + ); if (!name) { return this.modelLiteral(model); } @@ -330,7 +337,12 @@ export class OpenAPI3SchemaEmitterBase< items: this.emitter.emitTypeReference(elementType), }); - const name = getOpenAPITypeName(this.emitter.getProgram(), array, this.#typeNameOptions()); + const name = getComponentTypeName( + this.emitter.getProgram(), + array, + this.#typeNameOptions(), + this._options, + ); return this.#createDeclaration(array, name, this.applyConstraints(array, schema as any)); } @@ -542,7 +554,12 @@ export class OpenAPI3SchemaEmitterBase< } enumDeclaration(en: Enum, name: string): EmitterOutput { - const baseName = getOpenAPITypeName(this.emitter.getProgram(), en, this.#typeNameOptions()); + const baseName = getComponentTypeName( + this.emitter.getProgram(), + en, + this.#typeNameOptions(), + this._options, + ); return this.#createDeclaration(en, baseName, new ObjectBuilder(this.enumSchema(en))); } @@ -570,7 +587,12 @@ export class OpenAPI3SchemaEmitterBase< unionDeclaration(union: Union, name: string): EmitterOutput { const schema = this.unionSchema(union); - const baseName = getOpenAPITypeName(this.emitter.getProgram(), union, this.#typeNameOptions()); + const baseName = getComponentTypeName( + this.emitter.getProgram(), + union, + this.#typeNameOptions(), + this._options, + ); return this.#createDeclaration(union, baseName, schema); } @@ -835,7 +857,12 @@ export class OpenAPI3SchemaEmitterBase< const program = this.emitter.getProgram(); const shouldInline = isStdType(program, scalar) || isTypeRefType(program, scalar); const schema = this.#getSchemaForScalar(scalar); - const baseName = getOpenAPITypeName(this.emitter.getProgram(), scalar, this.#typeNameOptions()); + const baseName = getComponentTypeName( + this.emitter.getProgram(), + scalar, + this.#typeNameOptions(), + this._options, + ); // Built-in and compile-time scalars do not need declarations. return shouldInline diff --git a/packages/openapi3/test/component.test.ts b/packages/openapi3/test/component.test.ts index e00fa63df4f..5844b8d0f6a 100644 --- a/packages/openapi3/test/component.test.ts +++ b/packages/openapi3/test/component.test.ts @@ -1,5 +1,6 @@ import { expectDiagnostics } from "@typespec/compiler/testing"; import { describe, expect, it } from "vitest"; +import type { OpenAPI3EmitterOptions } from "../src/lib.js"; import type { OpenAPI3Document } from "../src/types.js"; import { supportedVersions, worksFor } from "./works-for.js"; @@ -237,6 +238,184 @@ const testCases: Case[] = [ ]; worksFor(supportedVersions, async (specHelpers) => { + describe("Component naming", () => { + const code = ` + @service namespace Demo { + namespace Models { + model User_Profile { id: string; } + } + @get op read(): Models.User_Profile; + } + `; + + it("preserves existing output with explicit defaults", async () => { + const current = await specHelpers.openApiFor(code); + const explicit = await specHelpers.openApiFor(code, { + "component-name-strategy": "fqn", + }); + expect(explicit).toEqual(current); + expect(current.components.schemas["Models.User_Profile"]).toBeDefined(); + }); + + it.each([ + { strategy: "name-only", name: "User_Profile" }, + { strategy: { kind: "fqn", separator: "_" }, name: "Models_User_Profile" }, + { strategy: { kind: "fqn", separator: "" }, name: "ModelsUser_Profile" }, + ] satisfies { + strategy: OpenAPI3EmitterOptions["component-name-strategy"]; + name: string; + }[])("uses $strategy for component keys and references", async ({ strategy, name }) => { + const doc = await specHelpers.openApiFor(code, { "component-name-strategy": strategy }); + expect(Object.keys(doc.components.schemas)).toEqual([name]); + expect(doc.paths["/"].get.responses["200"].content["application/json"].schema).toEqual({ + $ref: `#/components/schemas/${name}`, + }); + }); + + it("uses namespace separators across schema kinds without changing friendly or payload names", async () => { + const doc = await specHelpers.openApiFor( + ` + @service namespace Demo { + namespace Models { + scalar User_Id extends string; + enum User_Kind { normal } + union User_State { "active", "inactive" } + model User_List is User_Profile[]; + @friendlyName("Page-{name}", T) + model Page { value: T; } + model User_Profile { + user_id: User_Id; + kind: User_Kind; + state: User_State; + next?: Page; + } + } + @get op read(): Models.User_List; + } + `, + { "component-name-strategy": { kind: "fqn", separator: "_" } }, + ); + expect(Object.keys(doc.components.schemas)).toEqual([ + "Models_User_Id", + "Models_User_Kind", + "Models_User_List", + "Models_User_Profile", + "Models_User_State", + "Page-User_Profile", + ]); + expect(doc.components.schemas.Models_User_List.items.$ref).toBe( + "#/components/schemas/Models_User_Profile", + ); + expect(doc.components.schemas.Models_User_Profile.properties.user_id.$ref).toBe( + "#/components/schemas/Models_User_Id", + ); + expect(doc.components.schemas.Models_User_Profile.properties.next.$ref).toBe( + "#/components/schemas/Page-User_Profile", + ); + }); + + it("treats literal dots and friendly names as atomic names", async () => { + const doc = await specHelpers.openApiFor( + ` + @service namespace Demo { + namespace Models { + model \`User.Profile\` {} + @friendlyName("Friendly.Name") model Other {} + } + } + `, + { "component-name-strategy": { kind: "fqn", separator: "_" } }, + ); + expect(Object.keys(doc.components.schemas)).toEqual(["Friendly.Name", "Models_User.Profile"]); + }); + + it("omits namespaces while preserving discriminator references", async () => { + const doc = await specHelpers.openApiFor( + ` + @service namespace Demo { + namespace Models { + @discriminator("pet_kind") model Pet_Base { pet_kind: string; } + model House_Cat extends Pet_Base { pet_kind: "house_cat"; } + } + @get op read(): Models.Pet_Base; + } + `, + { + "component-name-strategy": "name-only", + }, + ); + expect(doc.components.schemas.Pet_Base.discriminator).toEqual({ + propertyName: "pet_kind", + mapping: { house_cat: "#/components/schemas/House_Cat" }, + }); + expect(doc.components.schemas.House_Cat.allOf).toEqual([ + { $ref: "#/components/schemas/Pet_Base" }, + ]); + }); + + it("omits namespaces for generated envelopes and visibility variants", async () => { + const doc = await specHelpers.openApiFor( + ` + namespace Models { + model House_Cat { + value: string; + @visibility(Lifecycle.Create) secret: string; + } + @discriminated union Pet_Choice { house_cat: House_Cat } + } + @put op update(@body data: Models.Pet_Choice): Models.Pet_Choice; + `, + { "component-name-strategy": "name-only" }, + ); + for (const suffix of ["", "CreateOrUpdate"]) { + expect(doc.components.schemas[`Pet_Choice${suffix}`].discriminator.mapping).toEqual({ + house_cat: `#/components/schemas/Pet_ChoiceHouse_cat${suffix}`, + }); + expect(doc.components.schemas[`Pet_ChoiceHouse_cat${suffix}`].properties.value.$ref).toBe( + `#/components/schemas/House_Cat${suffix}`, + ); + } + expect(doc.paths["/"].put.requestBody.content["application/json"].schema.$ref).toBe( + "#/components/schemas/Pet_ChoiceCreateOrUpdate", + ); + expect(doc.paths["/"].put.responses["200"].content["application/json"].schema.$ref).toBe( + "#/components/schemas/Pet_Choice", + ); + }); + + it("leaves external references and debugging names unchanged", async () => { + const doc = await specHelpers.openApiFor( + ` + @useRef("../common.json#/components/schemas/User_Profile") model External_User {} + namespace Models { model User_Profile { external: External_User; } } + model Box { value: T; } + @get op read(): Box; + `, + { + "component-name-strategy": "name-only", + "include-x-typespec-name": "inline-only", + }, + ); + const schema = doc.paths["/"].get.responses["200"].content["application/json"].schema; + expect(schema["x-typespec-name"]).toBe("Box"); + expect(schema.properties.value.$ref).toBe("#/components/schemas/User_Profile"); + expect(doc.components.schemas.User_Profile.properties.external.$ref).toBe( + "../common.json#/components/schemas/User_Profile", + ); + }); + + it("reports collisions after omitting namespaces", async () => { + const diagnostics = await specHelpers.diagnoseOpenApiFor( + ` + namespace A { model User {} } namespace B { model User {} } + op read(): A.User | B.User; + `, + { "component-name-strategy": "name-only" }, + ); + expectDiagnostics(diagnostics, { code: "@typespec/openapi/duplicate-type-name" }); + }); + }); + describe("Invalid component key", () => { it.each(testCases)( "$title should report diagnostics and replace by valid key", diff --git a/packages/openapi3/test/declaration-expressions.test.ts b/packages/openapi3/test/declaration-expressions.test.ts index 33658fdaef7..cde6ad18eea 100644 --- a/packages/openapi3/test/declaration-expressions.test.ts +++ b/packages/openapi3/test/declaration-expressions.test.ts @@ -1,7 +1,7 @@ import { expect, it } from "vitest"; import { supportedVersions, worksFor } from "./works-for.js"; -worksFor(supportedVersions, ({ oapiForModel }) => { +worksFor(supportedVersions, ({ oapiForModel, openApiFor }) => { it("inlines an anonymous enum used as a property type", async () => { const res = await oapiForModel("Foo", `model Foo { status: enum { active, inactive }; }`); const status = res.schemas.Foo.properties.status; @@ -35,4 +35,33 @@ worksFor(supportedVersions, ({ oapiForModel }) => { expect(res.schemas.Inner.properties.x.type).toBe("string"); expect(Object.keys(res.schemas).sort()).toEqual(["Foo", "Inner"]); }); + + it("does not qualify declaration expressions with their enclosing namespace", async () => { + const doc = await openApiFor( + ` + @service namespace Demo { + namespace Models { + model Outer { + inner: model Inner { value: string; }; + choice: enum Choice { active }; + code: scalar Code extends string; + } + } + @get op read(): Models.Outer; + } + `, + { "component-name-strategy": { kind: "fqn", separator: "_" } }, + ); + expect(Object.keys(doc.components.schemas)).toEqual([ + "Choice", + "Code", + "Inner", + "Models_Outer", + ]); + expect(doc.components.schemas.Models_Outer.properties).toEqual({ + inner: { $ref: "#/components/schemas/Inner" }, + choice: { $ref: "#/components/schemas/Choice" }, + code: { $ref: "#/components/schemas/Code" }, + }); + }); }); diff --git a/packages/openapi3/test/get-openapi.test.ts b/packages/openapi3/test/get-openapi.test.ts index 1d0757f8862..a7418151746 100644 --- a/packages/openapi3/test/get-openapi.test.ts +++ b/packages/openapi3/test/get-openapi.test.ts @@ -1,5 +1,5 @@ import { expectDiagnostics } from "@typespec/compiler/testing"; -import { ok, strictEqual } from "assert"; +import { deepStrictEqual, ok, strictEqual } from "assert"; import { it } from "vitest"; import { getOpenAPI3 } from "../src/openapi.js"; import { ApiTester } from "./test-host.js"; @@ -49,3 +49,31 @@ it("has diagnostics", async () => { }, ]); }); + +it("applies component naming independently to each service through the object API", async () => { + const { program } = await ApiTester.compile(` + import "@typespec/http"; + using Http; + @service namespace First { + namespace Models { model User_Profile { first: string; } } + @get op read(): Models.User_Profile; + } + @service namespace Second { + namespace Models { model User_Profile { second: string; } } + @get op read(): Models.User_Profile; + } + `); + const records = await getOpenAPI3(program, { + "component-name-strategy": "name-only", + }); + strictEqual(records.length, 2); + for (const [index, record] of records.entries()) { + ok(!record.versioned); + expectDiagnostics(record.diagnostics, []); + const schemas = record.document.components!.schemas!; + deepStrictEqual(Object.keys(schemas), ["User_Profile"]); + deepStrictEqual(Object.keys((schemas.User_Profile as any).properties), [ + index === 0 ? "first" : "second", + ]); + } +}); diff --git a/packages/openapi3/test/multipart.test.ts b/packages/openapi3/test/multipart.test.ts index 69b9ca33e93..90f2ca35800 100644 --- a/packages/openapi3/test/multipart.test.ts +++ b/packages/openapi3/test/multipart.test.ts @@ -4,6 +4,25 @@ import type { OpenAPI3Encoding, OpenAPI3Schema, OpenAPISchema3_1 } from "../src/ import { supportedVersions, worksFor } from "./works-for.js"; worksFor(supportedVersions, ({ openApiFor }) => { + it("uses configured component names for repeated named multipart bodies", async () => { + const res = await openApiFor( + ` + @service namespace Demo { + namespace Models { model Upload_Form { name: HttpPart; } } + @route("/a") op first(@multipartBody body: Models.Upload_Form): void; + @route("/b") op second(@multipartBody body: Models.Upload_Form): void; + } + `, + { "component-name-strategy": "name-only" }, + ); + expect(Object.keys(res.components.schemas)).toEqual(["Upload_Form"]); + for (const path of ["/a", "/b"]) { + expect(res.paths[path].post.requestBody.content["multipart/form-data"].schema).toEqual({ + $ref: "#/components/schemas/Upload_Form", + }); + } + }); + it("create dedicated model for multipart", async () => { const res = await openApiFor( ` diff --git a/packages/openapi3/test/parameters.test.ts b/packages/openapi3/test/parameters.test.ts index 77051702847..891e8e7599c 100644 --- a/packages/openapi3/test/parameters.test.ts +++ b/packages/openapi3/test/parameters.test.ts @@ -247,6 +247,76 @@ worksFor(supportedVersions, ({ diagnoseOpenApiFor, openApiFor, version }) => { ]); }); + it("names reusable parameter keys independently of wire names", async () => { + const doc = await openApiFor( + ` + @service namespace Demo { + namespace Models { + model Query_Options { + @query("page-size") page_size: int32; + @header("x-user-id") user_id: string; + } + model Single_Option { @query("sort-by") sort_by: string; } + } + @get op read(...Models.Query_Options, ...Models.Single_Option): void; + } + `, + { + "component-name-strategy": { kind: "name-only", separator: "_" }, + }, + ); + expect(Object.keys(doc.components.parameters)).toEqual([ + "Query_Options_page_size", + "Query_Options_user_id", + "Single_Option", + ]); + expect(doc.paths["/"].get.parameters).toEqual([ + { $ref: "#/components/parameters/Query_Options_page_size" }, + { $ref: "#/components/parameters/Query_Options_user_id" }, + { $ref: "#/components/parameters/Single_Option" }, + ]); + expect(doc.components.parameters.Query_Options_page_size.name).toBe("page-size"); + expect(doc.components.parameters.Query_Options_user_id.name).toBe("x-user-id"); + expect(doc.components.parameters.Single_Option.name).toBe("sort-by"); + }); + + it("reports parameter collisions after omitting namespaces", async () => { + const diagnostics = await diagnoseOpenApiFor( + ` + namespace A { model Paging_Options { @query a: string; } } + namespace B { model Paging_Options { @query b: string; } } + @route("/a") op first(...A.Paging_Options): void; + @route("/b") op second(...B.Paging_Options): void; + `, + { + "omit-unreachable-types": true, + "component-name-strategy": "name-only", + }, + ); + expectDiagnostics(diagnostics, { + code: "@typespec/openapi/duplicate-type-name", + message: /parameter/, + }); + }); + + it("uses the configured separator for shared parameter properties", async () => { + const doc = await openApiFor( + ` + model Paging { @query page_size: int32; @query page_number: int32; } + @get op read(...Paging): void; + `, + { "component-name-strategy": { kind: "fqn", separator: "_" } }, + ); + expect(doc.paths["/"].get.parameters).toEqual([ + { $ref: "#/components/parameters/Paging_page_size" }, + { $ref: "#/components/parameters/Paging_page_number" }, + ]); + expect(Object.keys(doc.components.parameters)).toEqual([ + "Paging_page_number", + "Paging_page_size", + ]); + }); + it("errors on invalid parameter keys", async () => { const diagnostics = await diagnoseOpenApiFor( ` diff --git a/website/src/content/docs/docs/emitters/openapi3/openapi.md b/website/src/content/docs/docs/emitters/openapi3/openapi.md index 1924f970d1c..611e2de5523 100644 --- a/website/src/content/docs/docs/emitters/openapi3/openapi.md +++ b/website/src/content/docs/docs/emitters/openapi3/openapi.md @@ -346,6 +346,24 @@ Models are handled differently based on how they're defined: [friendlyname]: ../../standard-library/built-in-decorators.md#@friendlyName +### Component Names + +By default, schema names include their namespace relative to the service, such as `Models.User_Profile`. A `@friendlyName` overrides that name. Reusable parameter keys use the same naming rules, with a property-name segment when the source model has multiple properties. + +Use `component-name-strategy` to omit namespaces or customize the separator between namespace and parameter-property segments: + +```yaml +options: + "@typespec/openapi3": + component-name-strategy: name-only +``` + +Alternatively, use `{ kind: fqn, separator: "_" }` to emit `Models_User_Profile`, or an empty separator to concatenate segments. Separators do not replace punctuation inside identifiers or friendly names. The default strategy is `fqn` with `"."` separators. + +The option affects schema and reusable parameter keys and their references, including named multipart schemas. It does not change operation IDs, HTTP parameter names, JSON property names, discriminator values, security-scheme names, or explicit `@useRef` URLs. Characters within identifiers and friendly names, such as underscores and hyphens, remain unchanged. + +Names that collide after namespace changes produce errors; the emitter does not append counters. Adjust identifiers, friendly names, or namespace settings to resolve these errors. + ### Type Mapping This table shows how TypeSpec types map to OpenAPI/JSON Schema types: diff --git a/website/src/content/docs/docs/emitters/openapi3/reference/emitter.md b/website/src/content/docs/docs/emitters/openapi3/reference/emitter.md index 7d9f3b5dd5e..84166f65fd1 100644 --- a/website/src/content/docs/docs/emitters/openapi3/reference/emitter.md +++ b/website/src/content/docs/docs/emitters/openapi3/reference/emitter.md @@ -166,6 +166,25 @@ See https://github.com/OAI/OpenAPI-Specification/discussions/4622 for discussion | `kind` | `"parent-container" \| "fqn" \| "explicit-only"` | `"parent-container"` | Determines how to generate operation IDs when `@operationId` is not used.
Avaliable options are:
- `parent-container`: Uses the parent namespace and operation name to generate the ID.
- `fqn`: Uses the fully qualified name of the operation to generate the ID.
- `explicit-only`: Only use explicitly defined operation IDs. | | `separator` | `string` | | Separator used to join segment in the operation name. | +### `component-name-strategy` + +**Type:** `"fqn" | "name-only" | object { kind, separator }` + +**Options:** + +- `"fqn" | "name-only"` (default: `"fqn"`) + + Naming strategy for schema and reusable parameter component keys. + `fqn` preserves service-relative namespace qualification; `name-only` omits namespaces. + Friendly names override namespace qualification. Operation IDs and HTTP names are unchanged. + +- `object { kind, separator }` + +| Name | Type | Default | Description | +| ----------- | ---------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `kind` | `"fqn" \| "name-only"` | `"fqn"` | Naming strategy for schema and reusable parameter component keys.
`fqn` preserves service-relative namespace qualification; `name-only` omits namespaces.
Friendly names override namespace qualification. Operation IDs and HTTP names are unchanged. | +| `separator` | `string` | `"."` | Separator between namespace and parameter-property segments. May be empty. Does not replace punctuation within identifiers or friendly names. | + ### `enum-strategy` **Type:** `"default" | "annotated"`