docfy export

ポートをバインドしたり稼働中のインフラを必要としたりせずに、プロジェクト自身のNestアプリを起動しOpenAPIドキュメントを書き出します。

存在理由

SwaggerModule.createDocument()が構造的に必要とする唯一のものは、完全に初期化されたNestアプリです。ルートとDTOのメタデータをイントロスペクトできるようになる前に、DIコンテナがすべてのプロバイダーを解決する必要があります。

これは.listen()を必要としません。ポートはバインドされません。

実際には、稼働中のインフラも通常は必要ありません。ほとんどのTypeOrmModule、ioredis、kafkajsクライアントはブートストラップをブロックせず遅延接続するため、exportはデータベース・Redis・Kafkaがすべて停止していても動作する傾向があります。

使い方

小さなエントリーファイルを用意してください(すでにmain.tsにある行から.listen()を除いたものです)。

ts
// docfy-export.ts
import { NestFactory } from '@nestjs/core';
import { DocumentBuilder, SwaggerModule } from '@nestjs/swagger';
import { AppModule } from './app.module';

export default async function () {
  const app = await NestFactory.create(AppModule, { logger: false });
  const config = new DocumentBuilder().setTitle('My API').setVersion('1.0.0').build();
  const document = SwaggerModule.createDocument(app, config);
  return { app, document }; // `app` gets closed for you afterward
}
bash
npx nestjs-docfy export --entry docfy-export.ts --out openapi.json

情報出力は常にstderrに送られ、stdoutには送られません。そのためパイプしても安全です: npx nestjs-docfy export --entry docfy-export.ts > openapi.json。

エントリーファイルの契約

デフォルトエクスポートは{ app, document }を返す非同期関数です。exportはこれを子プロセスで実行し、documentをシリアライズし、その後あなたに代わってapp.close()を呼び出します。

.tsエントリーには、プロジェクトのdevDependencyとしてts-nodeが必要です(@app/commonのようなパスエイリアスを使う場合はtsconfig-pathsも必要です)。

オプション

OptionDefaultDescription
--entry <path>(required).ts/.js file whose default export returns { app, document }
--out <path>stdoutWhere to write the document
--root <path>.Project root — where ts-node/tsconfig-paths are resolved from
--quietfalseSuppress informational output
これが役に立たない場合

コンストラクタやonModuleInitで本当に即座かつ致命的に失敗する接続を行うプロバイダーは、この方法でインフラをスキップしても恩恵を受けません。exportは、あなた自身のプロバイダーが接続する方法を何も変えられません。NestJS自体が必要としない唯一のもの、つまり開いたポートを回避するだけです。