Rush Stack商店博客活动
跳至主要内容

api-extractor.json

API 提取器的行为由一个配置文件**api-extractor.json**控制，该文件与您的项目存储在一起。您可以使用api-extractor init命令来创建模板文件以帮助您入门。该模板将包含描述每个设置的注释。它基于源代码中的api-extractor-template.json。

各个 JSON 字段在下面有详细说明。

顶级设置​

extends​

示例

  "extends": "./shared/api-extractor-base.json",
  "extends": "my-package/include/api-extractor-base.json",

默认值： ""

支持的标记： 无

可选地指定另一个 JSON 配置文件，该文件将从该文件中扩展。这为在多个项目之间共享标准设置提供了一种方法。

如果路径以./或../开头，则该路径将相对于包含extends字段的文件的文件夹解析。否则，第一个路径段将被解释为 NPM 包名称，并将使用 NodeJS require()解析。

projectFolder​

示例

  "projectFolder": "..",

默认值： "<lookup>"

支持的标记： <lookup>

确定可在其他配置文件设置中使用的<projectFolder>标记。项目文件夹通常包含**tsconfig.json**和**package.json**配置文件，但路径由用户定义。

该路径相对于包含该设置的配置文件的文件夹解析。

projectFolder的默认值为标记<lookup>，这意味着该文件夹是通过遍历父文件夹确定的，从包含 api-extractor.json 的文件夹开始，并在遇到包含**tsconfig.json**文件的第一个文件夹时停止。如果无法通过这种方式找到**tsconfig.json**文件，则会报告错误。

mainEntryPointFilePath​

(必需)

示例

  "mainEntryPointFilePath": "<projectFolder>/lib/index.d.ts",

支持的标记： <projectFolder>，<packageName>，<unscopedPackageName>

指定要用作分析起点的 .d.ts 文件。API 提取器会分析此模块导出的符号。

文件扩展名必须为 ".d.ts"，而不是 ".ts"。

该路径相对于包含该设置的配置文件的文件夹解析；要更改此路径，请在前面添加文件夹标记，例如<projectFolder>。

bundledPackages​

示例

  "bundledPackages": [ "library2", "@my-company/*" ],

NPM 包名称列表，其导出内容应被视为此包的一部分。

例如，假设 API 提取器在项目library1上运行，Webpack 用于为项目library1生成一个分布式包，另一个 NPM 包library2嵌入在此包中。library2中的一些类型可能成为library1导出的 API 的一部分，但默认情况下，API 提取器会生成一个 .d.ts 汇总，该汇总明确地导入library2。为了避免这种情况，我们可能像上面那样指定"bundledPackages": [ "library2" ]。这将指示 API 提取器直接在 .d.ts 汇总中嵌入这些类型，就好像它们是library1的本地文件一样。

"bundledPackages"元素可以使用minimatch语法指定 glob 模式。为了确保输出确定性，globs 通过显式匹配声明的顶级依赖项进行扩展。例如，上面的"@my-company/*"模式不会匹配@my-company/example，除非它出现在项目**package.json**文件的"dependencies"或"devDependencies"字段中。

newlineKind​

示例

  "newlineKind": "lf",

默认值： "crlf"

指定 API 提取器在写入输出文件时应使用哪种类型的换行符。默认情况下，输出文件将使用 Windows 风格的换行符写入。要使用 POSIX 风格的换行符，请改为指定"lf"。要使用操作系统的默认换行符种类，请指定"os"。

enumMemberOrder​

示例

  "enumMemberOrder": "preserve",

默认值： "by-name"

指定 API 提取器在生成 api.json 时对枚举成员进行排序的方式。默认情况下，输出文件将按字母顺序排序，即"by-name"。要保留源代码中的排序方式，请指定"preserve"。

testMode​

示例

  "testMode": true,

默认值： false

在调用 API 提取器的测试工具时设置为 true。当testMode为 true 时，.api.json 文件中的toolVersion字段将被分配一个空字符串，以防止输出文件中的虚假差异跟踪测试。

编译器部分​

确定 API 提取器将如何调用 TypeScript 编译器引擎。

compiler.tsconfigFilePath​

示例

  "tsconfigFilePath": "<projectFolder>/tsconfig.json",

默认值： "<projectFolder>/tsconfig.json"

支持的标记： <projectFolder>，<packageName>，<unscopedPackageName>

指定 API 提取器在分析项目时要使用的 tsconfig.json 文件的路径。

该路径相对于包含该设置的配置文件的文件夹解析；要更改此路径，请在前面添加文件夹标记，例如<projectFolder>。

注意：如果使用overrideTsconfig，则此设置将被忽略。

compiler.overrideTsconfig​

示例

  "compiler": {
    . . .
    "overrideTsconfig": {
      "$schema": "http://json.schemastore.org/tsconfig",

      "compilerOptions": {
        "target": "es5",
        "module": "commonjs",
        "declaration": true,
        "sourceMap": true,
        "declarationMap": true,
        "outDir": "lib"
      },
      "include": [
        "src/**/*.ts"
      ]
    },
    . . .
  }

默认值：没有 overrideTsconfig 部分

支持的标记： <projectFolder>，<packageName>，<unscopedPackageName>

提供一个编译器配置，该配置将用于代替从磁盘读取**tsconfig.json**文件。该对象必须符合TypeScript tsconfig 模式。

如果省略，则将从projectFolder读取**tsconfig.json**文件。

compiler.skipLibCheck​

示例

  "compiler": {
    . . .
    "skipLibCheck": true
  }

默认值： false

此选项导致编译器使用--skipLibCheck选项调用。此选项不推荐使用，可能会导致 API 提取器生成不完整或不正确的声明，但在依赖项包含与 API 提取器用于分析的 TypeScript 引擎不兼容的声明时可能需要使用。在可能的情况下，应修复根本问题，而不是依赖于skipLibCheck。

API 报告部分​

配置如何生成 API 报告文件（*.api.md）。

apiReport.enabled​

(必需)

示例

  "apiReport": {
    "enabled": true,
    . . .
  }

是否生成 API 报告。

apiReport.reportFileName​

示例

  "apiReport": {
    . . .
    "reportFileName": "<unscopedPackageName>",
    . . .
  }

默认值： "<unscopedPackageName>"

支持的标记： <packageName>，<unscopedPackageName>

API 报告文件的基文件名，与reportFolder或reportTempFolder组合以生成完整的文件路径。reportFileName不应包含任何路径分隔符，例如\或/。reportFileName不应包含文件扩展名，因为 API 提取器会自动附加适当的文件扩展名，例如.api.md。如果使用reportVariants设置，则文件扩展名包括变体名称，例如my-report.public.api.md或my-report.beta.api.md。"complete"变体始终使用简单扩展名my-report.api.md。

注意：API 提取器的先前版本要求reportFileName显式包含.api.md扩展名；为了向后兼容，仍然接受这种扩展名，但将在应用上述规则之前将其丢弃。

apiReport.reportVariants​

示例

  "apiReport": {
    . . .
    "reportVariants": [ "public", "beta" ],
    . . .
  }

默认值： [ "complete" ]

为了支持不同 API 级别不同的批准要求，可以生成 API 报告的多个“变体”。reportVariants设置指定要生成的变体列表。如果省略，默认情况下只生成"complete"变体，该变体包括所有@internal、@alpha、@beta和@public项。

变体名称包含的发布标签文件扩展名
"complete"@internal + @alpha + @beta + @publicmy-report.api.md
"alpha"@alpha + @beta + @publicmy-report.alpha.api.md
"beta"@beta + @publicmy-report.beta.api.md
"public"@public 仅供公开使用my-report.public.api.md

apiReport.reportFolder​

示例

  "apiReport": {
    . . .
    "reportFolder": "<projectFolder>/etc/",
    . . .
  }

默认值: "<projectFolder>/etc/"

支持的标记： <projectFolder>，<packageName>，<unscopedPackageName>

指定 API 报告文件写入的文件夹。 文件名部分由 reportFileName 设置决定。

API 报告文件通常由 Git 跟踪。 对它的更改可以用来触发分支策略，例如 API 审核。

该路径相对于包含该设置的配置文件的文件夹解析；要更改此路径，请在前面添加文件夹标记，例如<projectFolder>。

apiReport.reportTempFolder​

示例

  "apiReport": {
    . . .
    "reportTempFolder": "<projectFolder>/temp/",
    . . .
  }

默认值: "<projectFolder>/temp/"

支持的标记： <projectFolder>，<packageName>，<unscopedPackageName>

指定写入临时报告文件的文件夹。 文件名部分由 reportFileName 设置决定。

临时文件写入磁盘后，会与 reportFolder 中的文件进行比较。 如果它们不同，生产构建将失败。

该路径相对于包含该设置的配置文件的文件夹解析；要更改此路径，请在前面添加文件夹标记，例如<projectFolder>。

apiReport.includeForgottenExports​

示例

  "apiReport": {
    . . .
    "includeForgottenExports": true,
    . . .
  }

默认值： false

是否在 API 报告文件中包含“遗漏的导出”。 遗漏的导出是带有 ae-forgotten-export 警告的声明。

文档模型部分​

配置如何生成文档模型文件 (*.api.json)。

docModel.enabled​

(必需)

示例

  "docModel": {
    "enabled": true,
    . . .
  }

是否生成文档模型文件。

docModel.apiJsonFilePath​

示例

  "docModel": {
    . . .
    "apiJsonFilePath": "<projectFolder>/temp/<unscopedPackageName>.api.json",
    . . .
  }

默认值: "<projectFolder>/temp/<unscopedPackageName>.api.json"

支持的标记： <projectFolder>，<packageName>，<unscopedPackageName>

文档模型文件的输出路径。 文件扩展名应为 .api.json。

该路径相对于包含该设置的配置文件的文件夹解析；要更改此路径，请在前面添加文件夹标记，例如<projectFolder>。

docModel.includeForgottenExports​

示例

  "docModel": {
    . . .
    "includeForgottenExports": true,
    . . .
  }

默认值： false

是否在文档模型文件中包含“遗漏的导出”。 遗漏的导出是带有 ae-forgotten-export 警告的声明。

docModel.projectFolderUrl​

示例

  "docModel": {
    . . .
    "projectFolderUrl": "http://github.com/path/to/your/projectFolder"
  }

默认值： ""

项目源代码在 GitHub 或 Azure DevOps 等网站上查看的基 URL。 此 URL 路径对应于磁盘上的 <projectFolder> 路径。

此 URL 与序列化到文档模型的文件路径连接，以生成指向各个 API 项的 URL 文件路径。 例如，如果 projectFolderUrl 为 https://github.com/microsoft/rushstack/tree/main/apps/api-extractor 且 API 项的文件路径为 api/ExtractorConfig.ts，则完整的 URL 文件路径将为 https://github.com/microsoft/rushstack/tree/main/apps/api-extractor/api/ExtractorConfig.js。

如果您不需要 API 文档参考中的源代码链接，可以省略此设置。

.d.ts 汇总部分​

配置如何生成 .d.ts 汇总文件。

dtsRollup.enabled​

(必需)

示例

  "dtsRollup": {
    "enabled": true,
    . . .
  }

是否生成 .d.ts 汇总文件。

dtsRollup.untrimmedFilePath​

示例

  "dtsRollup": {
    . . .
    "untrimmedFilePath": "<projectFolder>/dist/<unscopedPackageName>.d.ts",
    . . .
  }

默认值: "<projectFolder>/dist/<unscopedPackageName>.d.ts"

支持的标记： <projectFolder>，<packageName>，<unscopedPackageName>

指定要生成的 .d.ts 汇总文件的输出路径，不进行任何修剪。 此文件将包含由主入口点导出的所有声明。

如果路径为空字符串，则不会写入此文件。

该路径相对于包含该设置的配置文件的文件夹解析；要更改此路径，请在前面添加文件夹标记，例如<projectFolder>。

dtsRollup.alphaTrimmedFilePath​

示例

  "dtsRollup": {
    . . .
    "betaTrimmedFilePath": "<projectFolder>/dist/<unscopedPackageName>-alpha.d.ts",
    . . .
  }

默认值： ""

支持的标记： <projectFolder>，<packageName>，<unscopedPackageName>

指定要生成的 .d.ts 汇总文件的输出路径，对“alpha”版本进行修剪。 此文件将仅包含标记为 @public、@beta 或 @alpha 的声明。

如果路径为空字符串，则不会写入此文件。

该路径相对于包含该设置的配置文件的文件夹解析；要更改此路径，请在前面添加文件夹标记，例如<projectFolder>。

dtsRollup.betaTrimmedFilePath​

示例

  "dtsRollup": {
    . . .
    "betaTrimmedFilePath": "<projectFolder>/dist/<unscopedPackageName>-beta.d.ts",
    . . .
  }

默认值： ""

支持的标记： <projectFolder>，<packageName>，<unscopedPackageName>

指定要生成的 .d.ts 汇总文件的输出路径，对“beta”版本进行修剪。 此文件将仅包含标记为 @public 或 @beta 的声明。

如果路径为空字符串，则不会写入此文件。

该路径相对于包含该设置的配置文件的文件夹解析；要更改此路径，请在前面添加文件夹标记，例如<projectFolder>。

dtsRollup.publicTrimmedFilePath​

示例

  "dtsRollup": {
    . . .
    "publicTrimmedFilePath": "<projectFolder>/dist/<unscopedPackageName>-public.d.ts",
    . . .
  }

默认值： ""

支持的标记： <projectFolder>，<packageName>，<unscopedPackageName>

指定要生成的 .d.ts 汇总文件的输出路径，对“public”版本进行修剪。 此文件将仅包含标记为 @public 的声明。

如果路径为空字符串，则不会写入此文件。

该路径相对于包含该设置的配置文件的文件夹解析；要更改此路径，请在前面添加文件夹标记，例如<projectFolder>。

dtsRollup.omitTrimmingComments​

示例

  "dtsRollup": {
    . . .
    "omitTrimmingComments": true,
    . . .
  }

默认值： false

修剪声明时，默认情况下将用代码注释替换，例如 Excluded from this release type: exampleMember。 将 omitTrimmingComments 设置为 true 以完全删除声明。

TSDoc 元数据部分​

配置如何生成 tsdoc-metadata.json 文件。

注意: tsdoc-metadata.json 的动机在 TSDoc RFC #7 中讨论。 API Extractor 的实现可以在 PackageMetadataManager.ts 中找到。

tsdocMetadata.enabled​

示例

  "tsdocMetadata": {
    "enabled": true,
    . . .
  }

默认值: true

是否生成 tsdoc-metadata.json 文件。

tsdocMetadata.tsdocMetadataFilePath​

示例

  "tsdocMetadata": {
    . . .
    "tsdocMetadataFilePath": "<projectFolder>/dist/tsdoc-metadata.json",
    . . .
  }

默认值： "<lookup>"

支持的标记： <projectFolder>，<packageName>，<unscopedPackageName>

指定应写入 TSDoc 元数据文件的位置。

该路径相对于包含该设置的配置文件的文件夹解析；要更改此路径，请在前面添加文件夹标记，例如<projectFolder>。

默认值为 <lookup>，这会导致从项目的 package.json 中的 tsdocMetadata、typings 或 main 字段自动推断路径。 如果这些字段都没有设置，则查找将回退到包文件夹中的 tsdoc-metadata.json。

消息报告部分​

配置 API Extractor 如何报告分析期间产生的错误和警告消息。

消息有三个来源：编译器消息、API Extractor 消息和 TSDoc 消息。

消息。<部分>.<规则>.logLevel​

示例

  "messages": {
    "compilerMessageReporting": {
      "default": {
        // Treat compiler messages as errors instead of warnings
        "logLevel": "error"
      }
    },
    . . .
  }

默认值: "warning"

可能值: "error"、"warning"、"none"

指定是否应将消息写入工具的输出日志。 请注意，addToApiReportFile 属性可能会覆盖此选项。

错误会导致构建失败并返回非零退出代码。 警告会导致生产构建失败并返回非零退出代码。 对于非生产构建（例如，当 api-extractor run 包含 --local 选项时），警告会显示，但构建不会失败。

消息。<部分>.<规则>.addToApiReportFile​

示例

  "messages": {
    "compilerMessageReporting": {
      "default": {
        "logLevel": "warning",

         // Don't break the build over compiler issues; instead write them to the API report
        "addToApiReportFile": true
      }
    },
    . . .
  }

默认值： false

当 addToApiReportFile 为 true 时：如果 API Extractor 配置为写入 API 报告文件 (.api.md)，则消息将写入该文件； 否则，消息将根据 logLevel 选项进行记录。

messages.compilerMessageReporting​

示例

  "messages": {
    "compilerMessageReporting": {
      "TS2551": {
        // Ignore TypeScript error TS2551 ("Property ___ does not exist on type ___")
        "logLevel": "none"
      }
    },
    . . .
  }

默认值

  "messages": {
    "compilerMessageReporting": {
      "default": {
        "logLevel": "warning"
      }
    },
    . . .
  }

配置处理分析输入 .d.ts 文件时 TypeScript 编译器引擎报告的诊断消息。

TypeScript 消息标识符以 TS 后跟一个整数开头。 例如：TS2551

messages.extractorMessageReporting​

示例

  "messages": {
    . . .
    "extractorMessageReporting": {
      "ae-extra-release-tag": {
        // Completely disable the "ae-extra-release-tag" validation
        "logLevel": "none"
      },
    },
    . . .
  }

默认值

(有关完整的最新表格，请参阅 api-extractor-defaults.json。)

  "messages": {
    . . .
    "extractorMessageReporting": {
      "default": {
        "logLevel": "warning"
      },
      "ae-forgotten-export": {
        "logLevel": "warning",
        "addToApiReportFile": true
      },
      "ae-incompatible-release-tags": {
        "logLevel": "warning",
        "addToApiReportFile": true
      },
      "ae-internal-missing-underscore": {
        "logLevel": "warning",
        "addToApiReportFile": true
      },
      "ae-unresolved-inheritdoc-reference": {
        "logLevel": "warning",
        "addToApiReportFile": true
      },
      "ae-unresolved-inheritdoc-base": {
        "logLevel": "warning",
        "addToApiReportFile": true
      }
    },
    . . .
  }

配置处理 API Extractor 在分析过程中报告的消息。

API Extractor 消息标识符以 ae- 开头。 例如：ae-extra-release-tag

messages.tsdocMessageReporting​

示例

  "messages": {
    . . .
    "tsdocMessageReporting": {
      "tsdoc-link-tag-unescaped-text": {
        // Completely disable the "tsdoc-link-tag-unescaped-text" validation
        "logLevel": "none"
      },
    }
  }

默认值

  "messages": {
    . . .
    "tsdocMessageReporting": {
      "default": {
        "logLevel": "warning"
      }
    }
  }

配置处理 TSDoc 解析器分析代码注释时报告的消息。

TSDoc 消息标识符以 tsdoc- 开头。 例如：tsdoc-link-tag-unescaped-text