diff --git a/apps/api-extractor/src/api/ExtractorConfig.ts b/apps/api-extractor/src/api/ExtractorConfig.ts index 7d0fb3c7319..c425de637d3 100644 --- a/apps/api-extractor/src/api/ExtractorConfig.ts +++ b/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, diff --git a/apps/api-extractor/src/api/IConfigFile.ts b/apps/api-extractor/src/api/IConfigFile.ts index e60def3af7e..cc1b444077e 100644 --- a/apps/api-extractor/src/api/IConfigFile.ts +++ b/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; } /** diff --git a/apps/api-extractor/src/generators/ApiReportGenerator.ts b/apps/api-extractor/src/generators/ApiReportGenerator.ts index 0a65c999507..c9b91706d79 100644 --- a/apps/api-extractor/src/generators/ApiReportGenerator.ts +++ b/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) { diff --git a/apps/api-extractor/src/schemas/api-extractor.schema.json b/apps/api-extractor/src/schemas/api-extractor.schema.json index 219b337e537..d02e8e318a5 100644 --- a/apps/api-extractor/src/schemas/api-extractor.schema.json +++ b/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"], diff --git a/build-tests/api-extractor-test-02/config/api-extractor.json b/build-tests/api-extractor-test-02/config/api-extractor.json index e4725c5edc7..5a601fd0f9c 100644 --- a/build-tests/api-extractor-test-02/config/api-extractor.json +++ b/build-tests/api-extractor-test-02/config/api-extractor.json @@ -4,7 +4,8 @@ "mainEntryPointFilePath": "/lib/index.d.ts", "apiReport": { - "enabled": true + "enabled": true, + "includeImports": false }, "docModel": { diff --git a/build-tests/api-extractor-test-02/etc/api-extractor-test-02.api.md b/build-tests/api-extractor-test-02/etc/api-extractor-test-02.api.md index 203ab2444d7..901fd45119a 100644 --- a/build-tests/api-extractor-test-02/etc/api-extractor-test-02.api.md +++ b/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 { // (undocumented) diff --git a/common/changes/@microsoft/api-extractor/omit-imports-from-api-reports_2024-05-31-22-13.json b/common/changes/@microsoft/api-extractor/omit-imports-from-api-reports_2024-05-31-22-13.json new file mode 100644 index 00000000000..fe8a3a0b111 --- /dev/null +++ b/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" +} \ No newline at end of file diff --git a/common/reviews/api/api-extractor.api.md b/common/reviews/api/api-extractor.api.md index 7b49ce35648..7043202d2fb 100644 --- a/common/reviews/api/api-extractor.api.md +++ b/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;