feat(typespec-autorest): add skip-example-copying emitter option and examples-dir version interpolation

.chronus/changes/skip-example-copying-2026-04-03-05-20-45.md

@@ -0,0 +1,7 @@
+---
+changeKind: feature
+packages:
+  - "@azure-tools/typespec-autorest"
+---
+
+Added `skip-example-copying` emitter option. When enabled, example files are not copied to the output directory and `x-ms-examples` `$ref` values point directly to the source example files via relative paths.

eng/feeds/__snapshots__/azure-arm/tspconfig.yaml

@@ -6,6 +6,8 @@ options:
     emitter-output-dir: "{project-root}"
     output-file: "{emitter-output-dir}/{version-status}/{version}/widget.json"
     arm-types-dir: "{project-root}/../../../../common-types/resource-management"
+    examples-dir: "{emitter-output-dir}/{version-status}/{version}/examples"
+    skip-example-copying: true
   "@azure-tools/typespec-csharp":
     emitter-output-dir: "{output-dir}/{service-dir}/Azure.ResourceManager.Contoso"
     clear-output-folder: true

eng/feeds/__snapshots__/azure-arm_stand_alone/tspconfig.yaml

@@ -4,6 +4,7 @@ options:
   "@azure-tools/typespec-autorest":
     use-read-only-status-schema: true
     output-file: "resource-manager/{service-name}/{version-status}/{version}/openapi.json"
+    examples-dir: "{project-root}/examples"
 linter:
   extends:
     - "@azure-tools/typespec-azure-rulesets/resource-manager"

eng/feeds/__snapshots__/azure-core/tspconfig.yaml

@@ -7,8 +7,10 @@ emit:
   - "@azure-tools/typespec-autorest"
 options:
   "@azure-tools/typespec-autorest":
-    emitter-output-dir: "{project-root}/.."
-    output-file: "data-plane/{service-name}/{version-status}/{version}/openapi.json"
+    emitter-output-dir: "{project-root}"
+    output-file: "{emitter-output-dir}/{version-status}/{version}/openapi.json"
+    examples-dir: "{emitter-output-dir}/{version-status}/{version}/examples"
+    skip-example-copying: true
   "@azure-tools/typespec-python":    
     emitter-output-dir: "{output-dir}/{service-dir}/azure-contoso"
     namespace: "azure.contoso"

eng/feeds/__snapshots__/azure-core_stand_alone/tspconfig.yaml

@@ -8,6 +8,7 @@ emit:
 options:
   "@azure-tools/typespec-autorest":
     output-file: "data-plane/{service-name}/{version-status}/{version}/openapi.json"
+    examples-dir: "{project-root}/examples"
   "@azure-tools/typespec-python":    
     emitter-output-dir: "{output-dir}/{service-dir}/azure-contoso"
     namespace: azure.contoso 

eng/feeds/arm-canonical/tspconfig.yaml

@@ -7,6 +7,8 @@ options:
     emitter-output-dir: "{project-root}"
     output-file: "{emitter-output-dir}/{version-status}/{version}/widget.json"
     arm-types-dir: "{project-root}/../../../../common-types/resource-management"
+    examples-dir: "{emitter-output-dir}/{version-status}/{version}/examples"
+    skip-example-copying: true
   "@azure-tools/typespec-autorest-canonical":
     emitter-output-dir: "{project-root}/.."
     output-file: "{emitter-output-dir}/canonical/openapi.json"

eng/feeds/arm/tspconfig.yaml

@@ -6,6 +6,8 @@ options:
     emitter-output-dir: "{project-root}"
     output-file: "{emitter-output-dir}/{version-status}/{version}/widget.json"
     arm-types-dir: "{project-root}/../../../../common-types/resource-management"
+    examples-dir: "{emitter-output-dir}/{version-status}/{version}/examples"
+    skip-example-copying: true
   "@azure-tools/typespec-csharp":
     emitter-output-dir: "{output-dir}/{service-dir}/Azure.ResourceManager.{{parameters.ServiceNamespace}}"
     clear-output-folder: true

eng/feeds/arm/tspconfig_stand_alone.yaml

@@ -4,6 +4,7 @@ options:
   "@azure-tools/typespec-autorest":
     use-read-only-status-schema: true
     output-file: "resource-manager/{service-name}/{version-status}/{version}/openapi.json"
+    examples-dir: "{project-root}/examples"
 linter:
   extends:
     - "@azure-tools/typespec-azure-rulesets/resource-manager"

eng/feeds/data-plane/tspconfig.yaml

@@ -9,6 +9,8 @@ options:
   "@azure-tools/typespec-autorest":
     emitter-output-dir: "{project-root}"
     output-file: "{emitter-output-dir}/{version-status}/{version}/openapi.json"
+    examples-dir: "{emitter-output-dir}/{version-status}/{version}/examples"
+    skip-example-copying: true
   "@azure-tools/typespec-python":    
     emitter-output-dir: "{output-dir}/{service-dir}/{{#normalizePackageName}}{{parameters.ServiceNamespace}}{{/normalizePackageName}}"
     namespace: "{{#toLowerCase}}{{parameters.ServiceNamespace}}{{/toLowerCase}}"

eng/feeds/data-plane/tspconfig_stand_alone.yaml

@@ -8,6 +8,7 @@ emit:
 options:
   "@azure-tools/typespec-autorest":
     output-file: "data-plane/{service-name}/{version-status}/{version}/openapi.json"
+    examples-dir: "{project-root}/examples"
   "@azure-tools/typespec-python":    
     emitter-output-dir: "{output-dir}/{service-dir}/{{#normalizePackageName}}{{parameters.ServiceNamespace}}{{/normalizePackageName}}"
     namespace: {{#toLowerCase}}{{parameters.ServiceNamespace}}{{/toLowerCase}} 

packages/typespec-autorest/README.md

@@ -170,6 +170,12 @@ Strategy for applying XML serialization metadata to schemas.
 
 Determines whether output should be split into multiple files. The only supported option for splitting is "legacy-feature-files", which uses the typespec-azure-resource-manager `@feature` decorators to split into output files based on feature.
 
+### `skip-example-copying`
+
+**Type:** `boolean`
+
+When enabled, the emitter will not copy example files to the output directory. Instead, it will reference the source example files using relative file paths.
+
 ## Decorators
 
 ### Autorest

packages/typespec-autorest/src/emit.ts

@@ -115,6 +115,7 @@ export function resolveAutorestOptions(
     emitCommonTypesSchema: resolvedOptions["emit-common-types-schema"],
     xmlStrategy: resolvedOptions["xml-strategy"],
     outputSplitting: resolvedOptions["output-splitting"],
+    skipExampleCopying: resolvedOptions["skip-example-copying"],
   };
 }
 
@@ -322,7 +323,7 @@ async function emitOutput(
   });
 
   // Copy examples to the output directory
-  if (result.operationExamples.length > 0) {
+  if (result.operationExamples.length > 0 && !options.skipExampleCopying) {
     const examplesPath = resolvePath(getDirectoryPath(result.outputFile), "examples");
     await program.host.mkdirp(examplesPath);
     for (const { examples } of result.operationExamples) {

packages/typespec-autorest/src/lib.ts

@@ -118,6 +118,13 @@ export interface AutorestEmitterOptions {
    * which uses the typespec-azure-resource-manager `@feature` decorators to split into output files based on feature.
    */
   "output-splitting"?: "legacy-feature-files";
+
+  /**
+   * When enabled, the emitter will not copy example files to the output directory.
+   * Instead, it will reference the source example files using relative file paths.
+   * @default false
+   */
+  "skip-example-copying"?: boolean;
 }
 
 const EmitterOptionsSchema: JSONSchemaType<AutorestEmitterOptions> = {
@@ -254,6 +261,13 @@ const EmitterOptionsSchema: JSONSchemaType<AutorestEmitterOptions> = {
       description:
         'Determines whether output should be split into multiple files.  The only supported option for splitting is "legacy-feature-files", which uses the typespec-azure-resource-manager `@feature` decorators to split into output files based on feature.',
     },
+    "skip-example-copying": {
+      type: "boolean",
+      nullable: true,
+      default: false,
+      description:
+        "When enabled, the emitter will not copy example files to the output directory. Instead, it will reference the source example files using relative file paths.",
+    },
   },
   required: [],
 };

packages/typespec-autorest/src/openapi.ts

@@ -254,6 +254,13 @@ export interface AutorestDocumentEmitterOptions {
    * Determines whether output should be split into multiple files.  The only supported option for splitting is "legacy-feature-files",
    */
   readonly outputSplitting?: "legacy-feature-files";
+
+  /**
+   * When enabled, example files will not be copied to the output directory.
+   * Instead, the source example files will be referenced using relative file paths.
+   * @default false
+   */
+  readonly skipExampleCopying?: boolean;
 }
 
 type HttpParameterProperties = Extract<
@@ -317,6 +324,13 @@ export async function getOpenAPIForService(
 
   const operationIdsWithExample = new Set<string>();
 
+  // Compute the example directory for resolving source example paths
+  const exampleDir = resolveExampleDir(
+    options.examplesDirectory,
+    program.projectRoot,
+    context.version,
+  );
+
   const [exampleMap, diagnostics] = await loadExamples(program, options, context.version);
   program.reportDiagnostics(diagnostics);
 
@@ -610,7 +624,15 @@ export async function getOpenAPIForService(
       operationIdsWithExample.add(currentEndpoint.operationId);
       currentEndpoint["x-ms-examples"] = currentEndpoint["x-ms-examples"] || {};
       for (const [title, example] of Object.entries(autoExamples)) {
-        currentEndpoint["x-ms-examples"][title] = { $ref: `./examples/${example.relativePath}` };
+        let ref: string;
+        if (options.skipExampleCopying) {
+          const sourceExamplePath = resolvePath(exampleDir, example.relativePath);
+          const outputDir = getDirectoryPath(context.outputFile);
+          ref = getRelativePathFromDirectory(outputDir, sourceExamplePath, false);
+        } else {
+          ref = `./examples/${example.relativePath}`;
+        }
+        currentEndpoint["x-ms-examples"][title] = { $ref: ref };
       }
     }
 
@@ -2799,6 +2821,34 @@ export function sortOpenAPIDocument(doc: OpenAPI2Document): OpenAPI2Document {
   return sorted;
 }
 
+/**
+ * Resolves the example directory path, supporting `{version}` and `{version-status}` interpolation
+ * variables in the `examples-dir` option.
+ *
+ * When the examples-dir contains `{version}` or `{version-status}`, these are interpolated
+ * with the actual version values and the resulting path is used directly.
+ * Otherwise, the version is appended as a subdirectory (legacy behavior).
+ */
+function resolveExampleDir(
+  examplesDirectory: string | undefined,
+  projectRoot: string,
+  version: string | undefined,
+): string {
+  const rawDir = examplesDirectory ?? resolvePath(projectRoot, "examples");
+  const hasVersionInterpolation =
+    rawDir.includes("{version}") || rawDir.includes("{version-status}");
+
+  if (hasVersionInterpolation) {
+    const versionStatus = version && (version.includes("preview") ? "preview" : "stable");
+    return interpolatePath(rawDir, {
+      "version-status": versionStatus,
+      version: version,
+    });
+  }
+
+  return version ? resolvePath(rawDir, version) : rawDir;
+}
+
 async function checkExamplesDirExists(host: CompilerHost, dir: string) {
   try {
     return (await host.stat(dir)).isDirectory();
@@ -2841,8 +2891,7 @@ async function loadExamples(
 ): Promise<[Map<string, Record<string, LoadedExample>>, readonly Diagnostic[]]> {
   const host = program.host;
   const diagnostics = createDiagnosticCollector();
-  const examplesBaseDir = options.examplesDirectory ?? resolvePath(program.projectRoot, "examples");
-  const exampleDir = version ? resolvePath(examplesBaseDir, version) : resolvePath(examplesBaseDir);
+  const exampleDir = resolveExampleDir(options.examplesDirectory, program.projectRoot, version);
 
   if (!(await checkExamplesDirExists(host, exampleDir))) {
     if (options.examplesDirectory) {