生成 API 文档
本文继续"调用 API 提取器"页面中的教程。建议从那里开始。
生成 JSON 文件
API 提取器将提取的 API 签名和文档注释写入名为“文档模型”文件的中间 JSON 文件。要启用此输出，只需在 api-extractor.json 配置文件中将 docModel.enabled 设置为 true 即可。
默认情况下，文档模型文件写入到 "<projectFolder>/temp/<unscopedPackageName>.api.json"，但您可以使用 docModel.apiJsonFilePath 设置自定义此路径。
使用 api-documenter 生成 Markdown
API 提取器包含一个名为 api-documenter 的配套工具，您可以使用它生成基本的 API 参考网站。Markdown 输出相当基本，因为 MarkdownDocumenter.ts 源文件旨在简洁易懂，同时功能完整。这样，它可以作为希望使用自定义管道（稍后讨论）实现自己的适配器来处理 API 提取器文档模型的人们的起点。即便如此，如果您的需求不是很花哨，Markdown 输出也是一个现实的解决方案，而且它非常易于使用。
作为输入，api-documenter 接受一个包含文档模型文件的文件夹，每个要包含的包都有一个文件。这允许单独构建一组相关项目（可能在单独的 Git 存储库中使用不同的工具链）。文档管道收集这些 JSON 文件，然后使用它们生成单个网站，其中包含跨包超链接和集成的导航树。
以下是一个典型的使用场景
（分别）为要记录的每个项目调用 API 提取器。这将生成一个或多个 .api.json 文件。
将 .api.json 文件复制到输入文件夹，例如
- ~/my-docs/input/ (.api.json 输入文件放在这里)
- ~/my-docs/markdown/ (.md 输出文件将放在这里)
使用如下 shell 命令将 api-documenter 工具 安装在您的全局环境中
$ npm install -g @microsoft/api-documenter假设您的
PATH环境变量设置正确，现在您应该能够从 shell 调用api-documenter。像这样运行 api-documenter 工具
$ cd ~/my-docs/
$ api-documenter markdown您可以使用
--input-folder和--output-folder等参数自定义这些文件夹。有关详细信息，请参阅命令行参考。
我们如何处理这些生成的 Markdown 文件？有多种选择
GitHub：如果您使用的是 GitHub，您可以简单地将它们提交到“docs”文件夹中的主分支，它们将使用 GitHub 的 markdown 预览器进行渲染。以下是如何显示的示例：node-core-library.md
GitHub Pages：如果您使用 GitHub Pages 为您的项目托管网站，您的存储库可能会有一个“gh-pages”分支。您可以在那里添加 Markdown 文件，如此处所示
示例分支：https://github.com/microsoft/rushstack-websites/tree/main/websites/api.rushstack.io/docs/pages
Docusaurus：这些 Markdown 文件也可以使用 Docusaurus 渲染，它使用 Markdown 输入生成基于 React 的网站。
示例分支：https://github.com/faastjs/faast.js/tree/master/docs/api
将 api-documenter 与 DocFX 结合使用
如果 Markdown 输出是文档生成的“卡丁车”，那么 DocFX 就是“航天飞机”。这是一个相当复杂但专业的系统，几乎拥有所有可以想象的功能，因为它被创建用来支持 docs.microsoft.com。就 API 提取器的参与而言，工作流程与上述相同，只是 shell 命令是 api-documenter yaml 而不是 api-documenter markdown。设置 DocFX 可能有点挑战性（除非您在 Microsoft 工作，在这种情况下非常简单！:-)）。
DocFX 生成的网站功能非常齐全。以下是一些使用 api-documenter 和 DocFX 生成的 API 参考
这些都是不错的选择。但是假设您有自定义需求，并且您不害怕编写一些代码来获得您想要的东西……