API 文档

本文继续了 "什么是 API 提取器？" 页面的教程。建议从那里开始。

我们将要看到的最终 API 提取器输出是“文档模型”文件。此 JSON 文件捕获了 API 签名和文档注释，用于 API 提取器处理的项目。它包含了生成 API 参考网站所需的所有信息。

该网站可以使用 API 提取器附带的基本 api-documenter 工具生成。您也可以将 JSON 文件用作自定义管道的输入。例如，真实的 @microsoft/sp-core-library 使用微软的自定义 DocFX 引擎进行渲染。以下是最终结果

https://docs.microsoft.com/en-us/javascript/api/sp-core-library

JSON 文件中有什么？

由于示例项目的 NPM 包名称是 @microsoft/sp-core-library，因此此输出的默认路径将是 temp/sp-core-library.api.json。该文件相当大，但这里有一个与 ILogHandler.error 成员相对应的摘录，应该可以了解文件结构

temp/sp-core-library.api.json

{
  "metadata": {
    "toolPackage": "@microsoft/api-extractor",
    "toolVersion": "7.1.0",
    "schemaVersion": 1000
  },
  "kind": "Package",
  "canonicalReference": "@microsoft/sp-core-library",
  "docComment": "",
  "name": "@microsoft/sp-core-library",
  "members": [
    {
      "kind": "EntryPoint",
      "canonicalReference": "",
      "name": "",
      "members": [
        {
          "kind": "Interface",
          "canonicalReference": "(ILogHandler:interface)",
          "docComment": "/**\n * The redirectable implementation for the Log class.\n *\n * @beta\n */\n",
          "releaseTag": "Beta",
          "name": "ILogHandler",
          "members": [
            {
              "kind": "MethodSignature",
              "canonicalReference": "(error:0)",
              "docComment": "",
              "excerptTokens": [
                {
                  "kind": "Reference",
                  "text": "error"
                },
                {
                  "kind": "Content",
                  "text": "("
                },
                . . .
              ],
              "returnTypeTokenRange": {
                "startIndex": 10,
                "endIndex": 11
              },
              "releaseTag": "Beta",
              "overloadIndex": 1,
              "parameters": [
                {
                  "parameterName": "source",
                  "parameterTypeTokenRange": {
                    "startIndex": 4,
                    "endIndex": 5
                  }
                },
                {
                  "parameterName": "error",
                  "parameterTypeTokenRange": {
                    "startIndex": 8,
                    "endIndex": 9
                  }
                }
              ],
              "name": "error"
            },
            . . .
          ],
          "extendsTokenRanges": []
        },
        . . .
      ]
    }
  ]
}

嗯，这很有趣……但有一个好消息：您不需要为这个复杂的文件格式编写自己的解析器！@microsoft/api-extractor-model 包已经提供了用于读取、查询、修改和写入此文件格式的完整库。如果您想自己编写 TypeScript 文档生成器，现在从未如此简单！:-)

共同记录多个项目

此中间 JSON 文件的一大优势是它允许将一组相关项目单独构建，但作为一个组进行记录。这在大型公司中特别有用，在大型公司中，各个项目可能由不同的团队拥有，可能在不同的 Git 存储库中工作，可能使用不同的工具链，可能在不同的时间表上发布。无论 JSON 文件是如何生成的，一旦它们被收集到一个中央位置，像 api-documenter 这样的工具就可以将它们加载到一个单一的“模型”中，并生成一个集成网站，包括跨包超链接和一个集成的导航树。

JSON 文件中有什么？​

共同记录多个项目​

JSON 文件中有什么？

共同记录多个项目