集成自定义文档管道

本文继续了 “调用 API 提取器” 页面上的教程。建议从那里开始。

在 上一页 上，我们讨论了各种文档系统，它们可以呈现由 api-documenter 工具创建的输出。但是，如果您想要自定义布局，或者想要与完全不同的系统集成呢？如果您不怕写一些代码，API 提取器会让这变得相当简单。

派生 api-documenter 项目

api-documenter 项目旨在用作代码示例，因此，如果您想进行一些小的更改，您可以简单地派生它并修改代码。以下是您可能想要查看的基本文件

• apps/api-documenter - GitHub 上的主要项目文件夹。

• MarkdownAction.ts - 此源文件定义了 api-documenter markdown 命令行及其参数。它加载 ApiModel 对象并将其传递给 MarkdownDocumenter。

• MarkdownDocumenter.ts - 这是您可能想要学习的主要文档生成器。它说明了如何遍历声明树并渲染每个 TypeScript 构造。由于 TSDoc 库 已经为表示富文本元素树提供了不错的 API，MarkdownDocumenter 类采用了一种方法，即生成一个巨大的 TSDoc “注释”，代表网站上的每个页面。这是一种不寻常的方法，但从 TSDoc 输入生成 TSDoc 输出可以避免必须转换所有内部内容。

• api-documenter/src/nodes - 此文件夹使用一些用于标题、表格、注释框等的自定义节点类型扩展了 TSDoc 库，这些节点类型是我们创建完整网页所需要的。

• MarkdownEmitter.ts - 此类是最终阶段，它从我们的 TSDoc “注释”（以及自定义节点）生成 Markdown 文档。这种分离可能在将来实现模块化：例如，如果我们想支持不同的 Markdown 风格，MarkdownDocumenter 类就不必关心这一点。从理论上讲，我们还可以从同一个中间 TSDoc 节点树发出完全不同的输出格式，例如 HTML。

编写自己的生成器

查看上面的组件，我们发现大部分代码都与文档内容的展示有关。访问所有 API 声明并渲染其各种属性的主要循环完全包含在 MarkdownDocumenter.ts 中，并且相对较小。

这是因为有了 @microsoft/api-extractor-model 库。它完成了加载 .api.json 文件夹、解析其内容以及提供一个可以查询的良好层次结构的艰苦工作。该库还实现了 ApiModel.resolveDeclarationReference() 函数，您可以使用它来解析声明引用，例如 @link 超链接。

@microsoft/api-extractor-model 的 README.md 解释了基本层次结构以及如何遍历它，并且诸如 ApiClass、ApiEnum、ApiInterface 等各个类都带有相当不错的代码注释。

一个可能不太明显的地方是如何将 TSDoc 渲染成除 Markdown 之外的其他格式。有关使用 React 渲染 HTML 的示例，您可能还想查看 DocHtmlView.tsx，它呈现了 TSDoc Playground 的 “HTML” 选项卡。

如果您遇到问题或有疑问，API 提取器开发人员通常可以在 rushstack 单仓库的 Zulip 聊天室 中联系到。

如果您实现了允许 API 提取器与酷炫的开源文档引擎一起工作的适配器... 请告诉我们！我们一定会在这份文档中提到它！ :-)