Provide an operation id resolver

.chronus/changes/operation-id-strategy-2025-9-1-16-38-40.md

@@ -0,0 +1,12 @@
+---
+# Change versionKind to one of: internal, fix, dependencies, feature, deprecation, breaking
+changeKind: feature
+packages:
+  - "@typespec/openapi3"
+---
+
+Add a new `operation-id-strategy` option.
+
+- `parent-container` (default and previous behavior) Join operation name with its parent if applicable with an underscore
+- `fqn` Join the path from the service root to the operation with `.`
+- `none` Do not generate operation ids, only include explicit ones set with `@operationId`

.chronus/changes/operation-id-strategy-2025-9-1-16-38-41.md

@@ -0,0 +1,8 @@
+---
+# Change versionKind to one of: internal, fix, dependencies, feature, deprecation, breaking
+changeKind: fix
+packages:
+  - "@typespec/openapi3"
+---
+
+Deduplicate operation ids that would resolve to the same one

.chronus/changes/operation-id-strategy-2025-9-1-18-43-58.md

@@ -0,0 +1,8 @@
+---
+# Change versionKind to one of: internal, fix, dependencies, feature, deprecation, breaking
+changeKind: feature
+packages:
+  - "@typespec/compiler"
+---
+
+[API] Allow using union in emitter schemas

packages/compiler/src/core/schema-validator.ts

@@ -35,6 +35,7 @@ export function createJSONSchemaValidator<T>(
   const ajv = new Ajv({
     strict: options.strict,
     coerceTypes: options.coerceTypes,
+    allowUnionTypes: true,
     allErrors: true,
   } satisfies Options);
 

packages/openapi3/README.md

@@ -134,6 +134,10 @@ Note: This is an experimental feature and may change in future versions.
 See https://spec.openapis.org/oas/v3.0.4.html#style-examples for parameter example serialization rules
 See https://github.com/OAI/OpenAPI-Specification/discussions/4622 for discussion on handling parameter examples.
 
+### `operation-id-strategy`
+
+**Type:** `undefined`
+
 ## Decorators
 
 ### TypeSpec.OpenAPI

packages/openapi3/package.json

@@ -33,6 +33,9 @@
       "default": "./dist/src/testing/index.js"
     }
   },
+  "imports": {
+    "#test/*": "./test/*"
+  },
   "engines": {
     "node": ">=20.0.0"
   },

packages/openapi3/src/lib.ts

@@ -91,8 +91,40 @@ export interface OpenAPI3EmitterOptions {
    * @see https://github.com/OAI/OpenAPI-Specification/discussions/4622 for discussion on handling parameter examples.
    */
   "experimental-parameter-examples"?: ExperimentalParameterExamplesStrategy;
+
+  /**
+   * How should operation ID be generated when `@operationId` is not used.
+   * Available options are
+   * - `parent-container`: Uses the parent namespace/interface and operation name to generate the ID.
+   * - `fqn`: Uses the fully qualified name(from service root) of the operation to generate the ID.
+   * - `explicit-only`: Only use explicitly defined operation IDs.
+   * @default parent-container
+   */
+  "operation-id-strategy"?:
+    | OperationIdStrategy
+    | {
+        /** Strategy used to generate the operation ID. */
+        kind: OperationIdStrategy;
+        /** Separator used to join segment in the operation name. */
+        separator?: string;
+      };
 }
 
+export type OperationIdStrategy = "parent-container" | "fqn" | "explicit-only";
+
+const operationIdStrategySchema = {
+  type: "string",
+  enum: ["parent-container", "fqn", "explicit-only"],
+  default: "parent-container",
+  description: [
+    "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.",
+  ].join("\n"),
+} as const;
+
 const EmitterOptionsSchema: JSONSchemaType<OpenAPI3EmitterOptions> = {
   type: "object",
   additionalProperties: false,
@@ -201,6 +233,23 @@ const EmitterOptionsSchema: JSONSchemaType<OpenAPI3EmitterOptions> = {
         "See https://github.com/OAI/OpenAPI-Specification/discussions/4622 for discussion on handling parameter examples.",
       ].join("\n"),
     },
+    "operation-id-strategy": {
+      oneOf: [
+        operationIdStrategySchema,
+        {
+          type: "object",
+          properties: {
+            kind: operationIdStrategySchema,
+            separator: {
+              type: "string",
+              nullable: true,
+              description: "Separator used to join segment in the operation name.",
+            },
+          },
+          required: ["kind"],
+        },
+      ],
+    } as any,
   },
   required: [],
 };

packages/openapi3/src/openapi.ts

@@ -78,15 +78,21 @@ import {
   getParameterKey,
   getTagsMetadata,
   isReadonlyProperty,
-  resolveOperationId,
   shouldInline,
 } from "@typespec/openapi";
 import { stringify } from "yaml";
 import { getRef } from "./decorators.js";
 import { getExampleOrExamples, OperationExamples, resolveOperationExamples } from "./examples.js";
 import { JsonSchemaModule, resolveJsonSchemaModule } from "./json-schema.js";
-import { createDiagnostic, FileType, OpenAPI3EmitterOptions, OpenAPIVersion } from "./lib.js";
+import {
+  createDiagnostic,
+  FileType,
+  OpenAPI3EmitterOptions,
+  OpenAPIVersion,
+  OperationIdStrategy,
+} from "./lib.js";
 import { getOpenApiSpecProps } from "./openapi-spec-mappings.js";
+import { OperationIdResolver } from "./operation-id-resolver/operation-id-resolver.js";
 import { getParameterStyle } from "./parameters.js";
 import { getOpenAPI3StatusCodes } from "./status-codes.js";
 import {
@@ -201,7 +207,6 @@ export function resolveOptions(
   const openapiVersions = resolvedOptions["openapi-versions"] ?? ["3.0.0"];
 
   const specDir = openapiVersions.length > 1 ? "{openapi-version}" : "";
-
   return {
     fileType,
     newLine: resolvedOptions["new-line"],
@@ -212,9 +217,37 @@ export function resolveOptions(
     openapiVersions,
     sealObjectSchemas: resolvedOptions["seal-object-schemas"],
     parameterExamplesStrategy: resolvedOptions["experimental-parameter-examples"],
+    operationIdStrategy: resolveOperationIdStrategy(resolvedOptions["operation-id-strategy"]),
   };
 }
 
+const defaultOperationIdStrategy = { kind: "parent-container", separator: "_" } as const;
+function resolveOperationIdStrategy(
+  strategy?: OperationIdStrategy | { kind: OperationIdStrategy; separator?: string },
+): { kind: OperationIdStrategy; separator: string } {
+  if (strategy === undefined) {
+    return defaultOperationIdStrategy;
+  }
+  if (typeof strategy === "string") {
+    return { kind: strategy, separator: resolveOperationIdDefaultStrategySeparator(strategy) };
+  }
+  return {
+    kind: strategy.kind,
+    separator: strategy.separator ?? resolveOperationIdDefaultStrategySeparator(strategy.kind),
+  };
+}
+
+function resolveOperationIdDefaultStrategySeparator(strategy: OperationIdStrategy) {
+  switch (strategy) {
+    case "parent-container":
+      return "_";
+    case "fqn":
+      return ".";
+    case "explicit-only":
+      return "";
+  }
+}
+
 export interface ResolvedOpenAPI3EmitterOptions {
   fileType: FileType;
   outputFile: string;
@@ -225,6 +258,7 @@ export interface ResolvedOpenAPI3EmitterOptions {
   safeintStrategy: "double-int" | "int64";
   sealObjectSchemas: boolean;
   parameterExamplesStrategy?: "data" | "serialized";
+  operationIdStrategy: { kind: OperationIdStrategy; separator: string };
 }
 
 function createOAPIEmitter(
@@ -241,7 +275,7 @@ function createOAPIEmitter(
   } = getOpenApiSpecProps(specVersion);
   const program = context.program;
   let schemaEmitter: AssetEmitter<OpenAPI3Schema | OpenAPISchema3_1, OpenAPI3EmitterOptions>;
-
+  let operationIdResolver: OperationIdResolver;
   let root: SupportedOpenAPIDocuments;
   let diagnostics: DiagnosticCollector;
   let currentService: Service;
@@ -368,6 +402,10 @@ function createOAPIEmitter(
       options,
       optionalDependencies,
     });
+    operationIdResolver = new OperationIdResolver(program, {
+      strategy: options.operationIdStrategy.kind,
+      separator: options.operationIdStrategy.separator,
+    });
 
     const securitySchemes = getOpenAPISecuritySchemes(allHttpAuthentications);
     const security = getOpenAPISecurity(defaultAuth);
@@ -730,7 +768,8 @@ function createOAPIEmitter(
   }
 
   function computeSharedOperationId(shared: SharedHttpOperation) {
-    const operationIds = shared.operations.map((op) => resolveOperationId(program, op.operation));
+    if (options.operationIdStrategy.kind === "explicit-only") return undefined;
+    const operationIds = shared.operations.map((op) => operationIdResolver.resolve(op.operation)!);
     const uniqueOpIds = new Set<string>(operationIds);
     if (uniqueOpIds.size === 1) return uniqueOpIds.values().next().value;
     return operationIds.join("_");
@@ -842,7 +881,7 @@ function createOAPIEmitter(
       parameterExamplesStrategy: options.parameterExamplesStrategy,
     });
     const oai3Operation: OpenAPI3Operation = {
-      operationId: resolveOperationId(program, operation.operation),
+      operationId: operationIdResolver.resolve(operation.operation),
       summary: getSummary(program, operation.operation),
       description: getDoc(program, operation.operation),
       parameters: getEndpointParameters(parameters.properties, visibility, examples),