API エクストラクターの起動

素晴らしいですね！では、新しいプロジェクトで API エクストラクターを有効にするにはどうすればよいでしょうか？

コマンドライン経由での起動

API エクストラクターを起動する最も簡単な方法は、コマンドラインを使用することです。

1. プロジェクトの TypeScript コンパイラを設定する

このチュートリアルでは、**package.json** ファイルが次のようになっている架空のライブラリプロジェクトがあるとします。

awesome-widgets/package.json

{
  "name": "awesome-widgets",
  "version": "1.0.0",
  "main": "./lib/index.js",
  "typings": "./lib/index.d.ts"
}

ここでは、ライブラリのメインエントリポイントが **awesome-widgets/src/index.ts** であり、コンパイルして上記の **index.js** および **index.d.ts** ファイルが生成されると想定しています。 **tsconfig.json** ファイルでは、次の設定を有効にする必要があります。

• "declaration": true - API エクストラクターが分析する .d.ts ファイルの生成を有効にします。*設計上、TypeScript ソースファイルは直接分析されず、最初にコンパイラによって処理される必要があります。*

• "declarationMap": true - API エクストラクターのエラーを元のソースファイルの行番号を使用して報告できるようにする .d.ts.map ファイルの生成を有効にします。これが無い場合、エラーの場所は生成された .d.ts ファイルを参照します。

サンプルの **tsconfig.json** ファイルは次のようになります。

awesome-widgets/tsconfig.json

{
  "$schema": "http://json.schemastore.org/tsconfig",
  "compilerOptions": {
    "target": "es5",
    "module": "commonjs",
    "declaration": true,
    "sourceMap": true,
    "declarationMap": true,
    "types": [
    ],
    "lib": [
      "es5"
    ],
    "outDir": "lib"
  },
  "include": [
    "src/**/*.ts"
  ]
}

2. API エクストラクターをインストールする

NPM パッケージをグローバル環境にインストールするには、次のようなコマンドを使用します。

$ npm install -g @microsoft/api-extractor

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

3. テンプレート設定ファイルを作成する

次に、プロジェクトの設定ファイル `api-extractor.json` を作成する必要があります。次のコマンドを実行すると、すべての設定とそのデフォルト値を示す テンプレートファイル が作成されます。

$ api-extractor init

このテンプレートを実設定ファイルに使用することをお勧めします。ただし、テンプレートはかなり冗長であるため、このチュートリアルでは、追加のコメントのない簡潔なファイルを示します。このページ では、各設定について詳しく説明しています。

JSON ファイルのコメント

厳密に言うと、JSON はもともとマシン交換フォーマットとして意図されていたため、コードコメントを正式にはサポートしていません。最近、JSON は人間が編集する設定ファイルフォーマットとして人気が高まっており、明らかにコメントが必要です。そのため、ほとんどの主要な JSON ライブラリは問題なくコメントを処理できます。（注目すべき例外は `JSON.parse()` です。これを使用しないでください。スキーマを検証できず、エラーレポートが不十分です。）

VS Code はデフォルトで JSON コメントをエラーとして強調表示しますが、オプションの "コメント付き JSON" モードを提供しています。これを有効にするには、VS Code の **settings.json** に次の行を追加します。

"files.associations": { "*.json": "jsonc" }

GitHub もデフォルトでコメントをエラーとして強調表示します。これを修正するには、**。gitattributes** ファイルに次の行を追加します。

*.json  linguist-language=JSON-with-Comments

他の可能性については、issue #1088 を参照してください。

私たちの規則では、設定ファイルを "config" サブフォルダーに配置するため、フォルダーツリーは次のようになります。

• awesome-widgets/package.json
• awesome-widgets/tsconfig.json
• awesome-widgets/config/api-extractor.json
• awesome-widgets/lib/index.d.js
• awesome-widgets/lib/index.js.map
• awesome-widgets/lib/index.d.ts
• awesome-widgets/lib/index.d.ts.map
• awesome-widgets/src/index.ts

プロジェクトで "config" サブフォルダーの規則を使用しない場合は、**api-extractor.json** をプロジェクトフォルダーに配置することもできます。API エクストラクターは両方の場所でそれを探します。

次の数ページでは、個々の設定について詳しく見ていきます。ここでは、`mainEntryPointFilePath` が上記の **package.json** ファイルの ` "typings"` フィールドと一致することを確認するだけです。テンプレートは次のように割り当てます。

  "mainEntryPointFilePath": "<projectFolder>/lib/index.d.ts",

...これは上記の **package.json** の ` "typings"` フィールドと一致します。

4. ツールの実行

これで、**api-extractor** コマンドラインを起動する準備が整いました。ローカル（非本番）ビルドの場合は、次のシェルコマンドを使用します。

$ cd awesome-widgets

# First invoke the TypeScript compiler to make the .d.ts files
$ tsc

# Next, we invoke API Extractor
$ api-extractor run --local --verbose

問題が発生した場合は、`--diagnostics` オプションを使用すると、問題の診断に役立つ追加情報が出力されます。

# Print troubleshooting logs
$ api-extractor run --local --diagnostics

コンパイラバージョンの非互換性

API エクストラクターがコンパイラエンジンを起動してプロジェクトを分析する場合、独自の TypeScript バージョンを使用します。コンパイラエンジン API が互換性がない可能性があるため、ツールチェーンのバージョンを使用することはできません。これにより、TypeScript バージョン間のシステム型の違いにより、API エクストラクターがコンパイラエラーを報告することがあります。これを回避するには、`--typescript-compiler-folder` コマンドラインオプション（API では `IExtractorInvokeOptions.typescriptCompilerFolder`）を指定します。これにより、API エクストラクターはツールチェーンの TypeScript フォルダーからシステム型を使用できます。

ツールチェーンが API エクストラクターのエンジンよりも新しいコンパイラリリースを使用していることが問題である場合は、API エクストラクターのコンパイラのアップグレードをリクエストする GitHub の issue を開いてください。私たちはできるだけ最新の状態を保つように努めています。

ビルドスクリプトからの起動

プロジェクトが TypeScript でコーディングされたカスタムツールチェーンを使用してビルドされている場合は、代わりに API エクストラクターエンジンをプログラムで起動できます。

多くのオプションがありますが、ここでは基本的な例を示します。

import * as path from 'path';
import { Extractor, ExtractorConfig, ExtractorResult } from '@microsoft/api-extractor';

const apiExtractorJsonPath: string = path.join(__dirname, '../config/api-extractor.json');

// Load and parse the api-extractor.json file
const extractorConfig: ExtractorConfig = ExtractorConfig.loadFileAndPrepare(apiExtractorJsonPath);

// Invoke API Extractor
const extractorResult: ExtractorResult = Extractor.invoke(extractorConfig, {
  // Equivalent to the "--local" command-line parameter
  localBuild: true,

  // Equivalent to the "--verbose" command-line parameter
  showVerboseMessages: true
});

if (extractorResult.succeeded) {
  console.log(`API Extractor completed successfully`);
  process.exitCode = 0;
} else {
  console.error(
    `API Extractor completed with ${extractorResult.errorCount} errors` +
      ` and ${extractorResult.warningCount} warnings`
  );
  process.exitCode = 1;
}

単一の **tsconfig.json** 環境に対して API エクストラクターを複数回起動する場合、このアプローチでは、複数の起動間で同じ `CompilerState` オブジェクトを再利用することもできます。TypeScript コンパイラの分析は比較的コストがかかるため、これは大幅なパフォーマンスの最適化になります。これを行う方法の実際の例については、api-extractor-scenarios/src/runScenarios.ts テストランナーを参照してください。

プロジェクト間での設定の再利用

**api-extractor.json** ファイルの内容は、`IConfigFile` インターフェースによって完全に記述されており、これを使用して `ExtractorConfig` オブジェクトを構築できます。このアプローチでは、**api-extractor.json** ファイルをまったく作成せずに済ませることができますが、一般的にはそうしないことをお勧めします。開発者が問題のトラブルシューティングを行う場合、人々が検査して操作できる標準の設定ファイルで実際の構成を表すことは非常に役立ちます。また、API エクストラクター自体をデバッグする必要がある場合は、複雑なツールチェーンよりも分離された `api-extractor` プロセスをデバッグする方がおそらく簡単ですが、そのためには **api-extractor.json** ファイルが必要になります。

では、多くの異なるプロジェクトを持つ最新のモノレポで作業している場合、**api-extractor.json** ファイルをたくさんコピー＆ペーストすることなく、それらに一貫した API エクストラクター設定をどのように確保できるでしょうか？ **tsconfig.json** および **tslint.json** の規則に従って、API エクストラクターは ` "extends"` フィールドをサポートしており、**api-extractor.json** ファイルが共有テンプレートファイルから設定を継承できます。詳細については、こちら を参照してください。

これで実行できるようになったので、3つの異なる出力タイプを設定する方法を見てみましょう...