Rush Stackショップブログイベント
本文へスキップ

APIドキュメントの生成

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

JSONファイルの生成​

API Extractorは、抽出されたAPI署名とドキュメントコメントを「ドキュメントモデル」ファイルと呼ばれる中間JSONファイルに書き込みます。この出力を有効にするには、**api-extractor.json**設定ファイルでdocModel.enabledをtrueに設定するだけです。

ドキュメントモデルファイルは、デフォルトで"<projectFolder>/temp/<unscopedPackageName>.api.json"に書き込まれますが、docModel.apiJsonFilePath設定を使用してカスタマイズできます。

api-documenterを使用したMarkdownの生成​

API Extractorには、基本的なAPIリファレンスウェブサイトを生成するために使用できるコンパニオンツールである**api-documenter**が含まれています。MarkdownDocumenter.tsソースファイルは簡潔で分かりやすいように設計されているため、Markdown出力は非常に基本的なものになっていますが、機能的には完全です。そのため、後で説明するカスタムパイプラインを使用してAPI Extractorのドキュメントモデルを処理する独自のアダプターを実装したい人の出発点として役立ちます。それでも、ニーズがあまり高度でない場合は、Markdown出力は現実的な解決策となり得る上、非常に使いやすいです。

入力として、**api-documenter**は、組み込みたい各パッケージのドキュメントモデルファイルを含むフォルダを受け入れます。これにより、関連するプロジェクトのコレクションを別々に（おそらく異なるツールチェーンを使用して別々のGitリポジトリで）ビルドできます。ドキュメントパイプラインはこれらのJSONファイルを収集し、それらを使用して、パッケージ間のハイパーリンクと統合されたナビゲーションツリーを備えた単一のウェブサイトを生成します。

一般的な使用シナリオを次に示します。

  1. （個別に）ドキュメント化したい各プロジェクトに対してAPI Extractorを実行します。これにより、1つ以上の.api.jsonファイルが生成されます。

  2. .api.jsonファイルを、たとえば次の入力フォルダにコピーします。

    • ~/my-docs/input/   （.api.json入力ファイルはこちら）
    • ~/my-docs/markdown/   （.md出力ファイルはこちら）

  3. 次のシェルコマンドを使用して、グローバル環境にapi-documenterツールをインストールします。

    $ npm install -g @microsoft/api-documenter

    PATH環境変数が正しく設定されていると仮定すると、シェルからapi-documenterを実行できるようになります。

  4. **api-documenter**ツールを次のように実行します。

    $ cd ~/my-docs/
    $ api-documenter markdown

    --input-folderや--output-folderなどのパラメーターを使用して、これらのフォルダをカスタマイズできます。詳細については、コマンドラインリファレンスを参照してください。

これらの生成されたMarkdownファイルで何をするのでしょうか？さまざまな選択肢があります。

DocFXを使用したapi-documenter​

Markdown出力がドキュメント生成の「ゴーカート」だとすれば、DocFXは「宇宙船」です。docs.microsoft.comを支えるために作成されたため、想像できるほぼすべての機能を備えた、かなり複雑ですがプロフェッショナルなシステムです。API Extractorの関与に関しては、上記のワークフローと同じですが、シェルコマンドはapi-documenter markdownではなくapi-documenter yamlになります。DocFXの設定は少し難しい場合があります（Microsoftで働いている場合は非常に簡単です！ :-)）。

DocFXによって生成されるサイトは非常に多機能です。次に、**api-documenter**とDocFXを使用して生成されたAPIリファレンスの例をいくつか示します。

これらは良い選択肢です。しかし、カスタムのニーズがあり、自分の欲しいものを得るためにコードを書くことを恐れないとしましょう…