Rush Stackショップブログイベント
メインコンテンツへスキップ

APIドキュメント

この記事は、「API Extractorとは?」ページのチュートリアルを続けます。そこから始めることをお勧めします。

最後に確認するAPI Extractorの出力は、「ドキュメントモデル」ファイルです。このJSONファイルは、API Extractorによって処理されたプロジェクトのAPIシグネチャとドキュメントコメントをキャプチャします。APIリファレンスWebサイトを生成するために必要なすべての情報が含まれています。

Webサイトは、API Extractorに付属している基本的なapi-documenterツールを使用して生成できます。JSONファイルを独自のカスタムパイプラインの入力として使用することもできます。たとえば、実際の@microsoft/sp-core-libraryは、MicrosoftのカスタムDocFXエンジンを使用してレンダリングされます。最終結果は次のとおりです。

https://docs.microsoft.com/ja-jp/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などのツールはそれらを単一の「モデル」にロードし、クロスパッケージハイパーリンクと統合ナビゲーションツリーを備えた統合Webサイトを生成できます。

これで、API Extractorの3つの主要なユースケースの簡単なツアーは終わりです。始める準備はできましたか?