APIレポート

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

最初に説明するAPI Extractorの出力は、「APIレポートファイル」です。例として使用しているライブラリのNPMパッケージ名が@microsoft/sp-core-libraryであるため、デフォルトのAPIレポートファイル名はetc/sp-core-library.api.mdになります。

レポートは、APIシグネチャを簡潔にまとめた疑似コードの大きなブロックで構成されたMarkdownファイルです。（API Extractor 7以前は、レポートは.api.tsファイル拡張子を使用していましたが、これは疑似コードを実際のTypeScriptコードとして解釈しようとするツールで問題を引き起こしました。）APIレポートの内容は次のようになります。

etc/sp-core-library.api.md

## API Report File for "@microsoft/sp-core-library"

> Do not edit this file. It is a report generated by [API Extractor](https://api-extractor.dokyumento.jp/).

```ts
// @beta
interface ILogHandler {
  // (undocumented)
  error(source: string, error: Error): void;
  // (undocumented)
  info(source: string, message: string): void;
  // (undocumented)
  verbose(source: string, message: string): void;
  // (undocumented)
  warn(source: string, message: string): void;
}

// @public
class Log {
  // @beta
  public static initialize(logHandler: ILogHandler): void;
  public static error(source: string, error: Error): void;
  public static info(source: string, message: string): void;
  public static verbose(source: string, message: string): void;
  public static warn(source: string, message: string): void;
}
```

レポートファイルはGitで追跡されます。開発者がローカルPCでLogクラスを変更したとします。ローカルで再構築する場合（たとえば、api-extractorツールの--localコマンドラインオプションを使用する場合）、レポートファイルが変更されたことを示すメッセージが表示されます。

[17:01:21] Starting subtask 'api-extractor'...
[17:01:28] [api-extractor] You have changed the Public API signature for this
project.  Updating 'etc/sp-core-library.api.md'
[17:01:28] Finished subtask 'api-extractor' after 0.54 s

開発者は、更新されたレポートファイルをコミットし、プルリクエスト（PR）の一部として含める必要があります。これを忘れると、PRの検証は、プロダクションビルド（つまり、--localを使用しない）を実行するため、レポートファイルが自動的に更新されないため、失敗します。その場合、PRビルドログに次のようなエラーメッセージが表示されます。

[17:03:37] Starting subtask 'api-extractor'...
[17:03:44] Warning - [api-extractor] You have changed the public API signature for this project.
Please copy the file "temp/sp-core-library.api.md" to "etc/sp-core-library.api.md", or perform
a local build (which does this automatically). See the Git repo documentation for more info.
[17:03:44] Finished subtask 'api-extractor' after 0.56 s

この設計により、PRの変更セットに.api.mdファイル拡張子が含まれる場合は常に、プロジェクトの関係者からの承認を要求するPRブランチポリシーを定義できます。軽率な承認は面倒な場合があるため、APIレポートファイルは、重要な契約上の変更が発生した場合にのみ差分が発生するように設計されています。

どのような変更が重要だと考えられるのでしょうか？レビュー担当者の視点から

関数シグネチャの変更は気になりますが、関数本体（つまり、コードのすべての行）は気にしません。
エクスポートされた宣言（サンプルプロジェクトのLogやILogHandlerなど）の変更は知りたいですが、エクスポートされていない宣言（DefaultLogHandlerなど）やプライベートクラスメンバーは知りたくありません。
ドキュメントが書かれているかどうか（「// (ドキュメントなし)」警告の有無など）は気になりますが、文章が変更されるたびに知る必要はありません。
項目のリリースステータス（@internal、@alpha、@beta、または@public）は気にしますが、他のほとんどのドキュメントコメントタグは無視します。
通常、@internal定義は、ファーストパーティのコンシューマーに影響を与えるため監視する必要があります（ただし、特定のクラスでは、@preapprovedタグを使用してこれを抑制できます）。

この概要を1つのレビューしやすいレポートにまとめることは非常に強力です。プロジェクトでAPI Extractorを有効にすると、多くの場合、啓発的な瞬間になります。（「それはそこで何をしているんだ？！これらの名前は非常に紛らわしい！なぜ誰もドキュメントを書かなかったんだ？！」など）。人々は毎日プロジェクトのソースファイルを使用していますが、それを視覚化する方法がなければ、全体像を見失いがちです。