API レポートの設定

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

API レポートファイルの設定は比較的簡単です。最も興味深い設定は次の 2 つです。

apiReport.enabled - レポートを生成するかどうか
apiReport.reportFolder - レポートが保存されるフォルダ

単一のプロジェクトの場合、レポートをデフォルトの場所 "<projectFolder>/etc/" に保持しても問題ありません。一方、多くのプロジェクトがあるモノレポで作業している場合は、API Extractor が開発されている rushstack リポジトリで使用されている common/reviews/api のような中央の場所にすべての API レポートファイルを書き込むことをお勧めします。

レポートファイルは Git で追跡される必要があり、API シグネチャの変更はプルリクエスト（PR）が作成されたときに差分として表示されます。

rushstack リポジトリでは、API が変更されたときに特定の人々のリストからの承認を要求するために、.github/CODEOWNERS ファイルを使用しています。プロセスに応じて、この承認は多かれ少なかれ形式化できます。

警告を API レポートファイルにリダイレクトする

ところで、API レポートファイルは特定の警告タイプを追跡するためにも使用できます。たとえば、ae-forgotten-export 検証は一般的に役立ちますが、意図的に宣言をエクスポートしたくない特定のケースがあるとします。

通常、警告は次のようにコンソールに出力されます。

Warning: (ae-forgotten-export) The symbol "IWidget" needs to be exported by
the entry point index.d.ts

コンソールの警告により、api-extractor ツールはゼロ以外の終了コードを返し、これにより本番ビルドが失敗します。ただし、addToApiReportFile 設定を使用すると、代わりに API レポートファイルに追加されるように警告を構成できます。api-extractor.json ファイルに次のようなセクションを追加します。

awesome-widgets/config/api-extractor.json

  . . .
  "messages": {
    "extractorMessageReporting": {
      "ae-forgotten-export": {
        "logLevel": "warning",
        "addToApiReportFile": true
      },
    },
    . . .
  },
  . . .

コンソールに警告を出力する代わりに、レポートファイルに次のようなものが表示されます。

awesome-widgets/etc/api-extractor.api.md

// Warning: (ae-forgotten-export) The symbol "IWidget" needs to be exported
// by the entry point index.d.ts
//
// @public
export class Widget implements IWidget {}

api-extractor-defaults.json を見ると、API Extractor は多くのメッセージタイプに対してデフォルトでこれを行っていることがわかります。一般に、問題が深刻ではないが、修正にはかなりの労力が必要となる場合や、API に重大な影響を与える可能性があるメッセージについては、デフォルトで true になります。

警告を API レポートファイルにリダイレクトする​

警告を API レポートファイルにリダイレクトする