[api-extractor] Allow omission of import statements in API reports

apps/api-extractor/src/api/ExtractorConfig.ts

@@ -186,6 +186,7 @@ interface IExtractorConfigParameters {
   reportFolder: string;
   reportTempFolder: string;
   apiReportIncludeForgottenExports: boolean;
+  apiReportIncludeImports: boolean;
   docModelEnabled: boolean;
   apiJsonFilePath: string;
   docModelIncludeForgottenExports: boolean;
@@ -305,6 +306,9 @@ export class ExtractorConfig {
   /** {@inheritDoc IConfigApiReport.includeForgottenExports} */
   public readonly apiReportIncludeForgottenExports: boolean;
 
+  /** {@inheritDoc IConfigApiReport.includeImports} */
+  public readonly apiReportIncludeImports: boolean;
+
   /** {@inheritDoc IConfigDocModel.enabled} */
   public readonly docModelEnabled: boolean;
   /** {@inheritDoc IConfigDocModel.apiJsonFilePath} */
@@ -368,6 +372,7 @@ export class ExtractorConfig {
     this.skipLibCheck = parameters.skipLibCheck;
     this.apiReportEnabled = parameters.apiReportEnabled;
     this.apiReportIncludeForgottenExports = parameters.apiReportIncludeForgottenExports;
+    this.apiReportIncludeImports = parameters.apiReportIncludeImports;
     this.reportConfigs = parameters.reportConfigs;
     this.reportFolder = parameters.reportFolder;
     this.reportTempFolder = parameters.reportTempFolder;
@@ -1102,6 +1107,7 @@ export class ExtractorConfig {
         reportFolder,
         reportTempFolder,
         apiReportIncludeForgottenExports,
+        apiReportIncludeImports: configObject.apiReport?.includeImports ?? true, // default: true
         docModelEnabled,
         apiJsonFilePath,
         docModelIncludeForgottenExports,

apps/api-extractor/src/api/IConfigFile.ts

@@ -141,6 +141,13 @@ export interface IConfigApiReport {
    * @defaultValue `false`
    */
   includeForgottenExports?: boolean;
+
+  /**
+   * Whether import statements should be included in the API report file.
+   *
+   * @defaultValue `true`
+   */
+  includeImports?: boolean;
 }
 
 /**

apps/api-extractor/src/generators/ApiReportGenerator.ts

@@ -82,13 +82,15 @@ export class ApiReportGenerator {
     }
     writer.ensureSkippedLine();
 
-    // Emit the imports
-    for (const entity of collector.entities) {
-      if (entity.astEntity instanceof AstImport) {
-        DtsEmitHelpers.emitImport(writer, entity, entity.astEntity);
+    // Emit the imports (if specified by the configuration)
+    if (collector.extractorConfig.apiReportIncludeImports) {
+      for (const entity of collector.entities) {
+        if (entity.astEntity instanceof AstImport) {
+          DtsEmitHelpers.emitImport(writer, entity, entity.astEntity);
+        }
       }
+      writer.ensureSkippedLine();
     }
-    writer.ensureSkippedLine();
 
     // Emit the regular declarations
     for (const entity of collector.entities) {

apps/api-extractor/src/schemas/api-extractor.schema.json

@@ -94,6 +94,12 @@
         "includeForgottenExports": {
           "description": "Whether \"forgotten exports\" should be included in the API report file. Forgotten exports are declarations flagged with `ae-forgotten-export` warnings. See https://api-extractor.com/pages/messages/ae-forgotten-export/ to learn more.",
           "type": "boolean"
+        },
+
+        "includeImports": {
+          "description": "Whether or not to include import statements in the API report file(s).",
+          "type": "boolean",
+          "default": true
         }
       },
       "required": ["enabled"],

build-tests/api-extractor-test-02/config/api-extractor.json

@@ -4,7 +4,8 @@
   "mainEntryPointFilePath": "<projectFolder>/lib/index.d.ts",
 
   "apiReport": {
-    "enabled": true
+    "enabled": true,
+    "includeImports": false
   },
 
   "docModel": {

build-tests/api-extractor-test-02/etc/api-extractor-test-02.api.md

@@ -4,10 +4,6 @@
 
 ```ts
 
-import { ISimpleInterface } from 'api-extractor-test-01';
-import { ReexportedClass as RenamedReexportedClass3 } from 'api-extractor-test-01';
-import * as semver1 from 'semver';
-
 // @public
 export interface GenericInterface<T> {
     // (undocumented)

common/changes/@microsoft/api-extractor/omit-imports-from-api-reports_2024-05-31-22-13.json

@@ -0,0 +1,10 @@
+{
+  "changes": [
+    {
+      "packageName": "@microsoft/api-extractor",
+      "comment": "Add support for omitting import statements from API reports",
+      "type": "minor"
+    }
+  ],
+  "packageName": "@microsoft/api-extractor"
+}

common/reviews/api/api-extractor.api.md

@@ -54,6 +54,7 @@ export class ExtractorConfig {
     readonly apiJsonFilePath: string;
     readonly apiReportEnabled: boolean;
     readonly apiReportIncludeForgottenExports: boolean;
+    readonly apiReportIncludeImports: boolean;
     readonly betaTrimmedFilePath: string;
     readonly bundledPackages: string[];
     readonly docModelEnabled: boolean;
@@ -182,6 +183,7 @@ export interface ICompilerStateCreateOptions {
 export interface IConfigApiReport {
     enabled: boolean;
     includeForgottenExports?: boolean;
+    includeImports?: boolean;
     reportFileName?: string;
     reportFolder?: string;
     reportTempFolder?: string;