DocfyUiModule.setup(mountPath, app, options?)
mountPathでdocfy-ui(本パッケージのAIファーストなコンパニオンドキュメントUI)を提供します。生のSwagger UIに対する<code>SwaggerModule.setup()</code> + <code>swagger-ui-express</code>と同じ役割です。
使い方
Express(@nestjs/platform-express)とFastify(@nestjs/platform-fastify)のどちらのアプリでも動作します。Fastifyでは静的アセット配信にオプションのピア依存関係@fastify/static(npm install @fastify/static)が必要です。@nestjs/swagger自体がFastifyのSwagger UIサポートのために利用しているのと同じパッケージです。
import { NestFactory } from '@nestjs/core';
import { SwaggerModule, DocumentBuilder } from '@nestjs/swagger';
import { DocfyUiModule } from 'nestjs-docfy';
const app = await NestFactory.create(AppModule);
DocfyUiModule.setup('/docs', app); // before SwaggerModule.setup; see staticSpecPath below
const document = SwaggerModule.createDocument(app, new DocumentBuilder().build());
SwaggerModule.setup('api', app, document); // exposes /api-json, which docfy-ui fetches by default
await app.listen(3000);/docsにアクセスしてください。追加の設定は不要です。docfy-uiはデフォルトで同一オリジンの/api-jsonを取得するためです。
オプション
| Option | Type | Default | Description |
|---|---|---|---|
staticSpecPath | string | なし | Path to a pre-built OpenAPI JSON file, served at /api-json instead of the app's live one. |
specs | { name: string; url: string }[] | なし | Extra OpenAPI specs to offer in docfy-ui's spec switcher, so one deployed instance can browse more than one service's documentation. |
openApiDocument | { servers?: { url: string }[] } | なし | Enables the "Try it out" same-origin proxy — pass the same object you already have from SwaggerModule.createDocument(). See below. |
additionalProxyOrigins | string[] | なし | Extra origins the proxy is allowed to forward requests to, beyond what openApiDocument.servers declares. |
guides | { slug, title, content }[] | なし | Narrative markdown pages at /guides/:slug, listed in the sidebar. A guide can embed a live, runnable request via a docfy-try fenced block (single line METHOD /path matching an endpoint in the current spec) — renders the endpoint's real request panel inline instead of just linking to its page. |
staticSpecPath(CLIプラグインを使わない場合、webpack: trueの下で必要)
DocfyModuleのランタイムメタデータパイプラインはそこにdocsファイルを適用できないため、稼働中の/api-jsonにはdocsファイルが追加するはずの内容がすべて欠落します。推奨される自動的な修正方法についてはThe CLI pluginを参照してください。ここでは手動の代替手段を扱います。あらかじめパッチ済みのドキュメントを生成します。
npx nestjs-docfy patch-spec --spec http://localhost:3000/api-json --out openapi.patched.jsonそしてそれを配信します。
DocfyUiModule.setup('/docs', app, { staticSpecPath: './openapi.patched.json' });これはSwaggerModule.setup()の前に呼び出してください。Expressは登録順にルートを解決するため、パッチ済みの静的ドキュメントが/api-jsonへのあらゆるリクエストに対して稼働中のものより優先されます。Fastifyでは、SwaggerModule.setup()が同時に独自の/api-jsonルートを登録しようとすると、起動時にFST_ERR_DUPLICATED_ROUTEが発生します。登録順は役に立たないため、FastifyでstaticSpecPathと組み合わせる場合はSwaggerModule.setup()を別のjsonDocumentUrlに向けるか、{ raw: false }を渡してください。
同一オリジンプロキシ
docfy-uiの「Try it out」用の同一オリジンプロキシを有効にします。これを使わない場合、リクエストの実行はブラウザから対象APIへ直接fetchが行われ、そのAPI自身のCORSポリシーに従うことになります。有効にすると、このモジュールが同一オリジンのルート()を登録し、ブラウザはそちらを呼び出すようになります。プロキシがサーバー間で実際のリクエストを行うため、CORSは一切適用されません。すでにSwaggerModule.createDocument()から得ているのと同じドキュメントを渡します。
const document = SwaggerModule.createDocument(app, new DocumentBuilder().build());
SwaggerModule.setup('api', app, document);
DocfyUiModule.setup('/docs', app, { openApiDocument: document });プロキシの許可リストは、ドキュメントのservers[]配列にある絶対URLと、additionalProxyOriginsにあるものだけから構築されます。クライアントが制御できるHostヘッダーから導出することになり、典型的なSSRFベクターとなるため、暗黙の「このリクエストと同一オリジン」というフォールバックは意図的に存在しません。それ以外のオリジンへのリクエストはとレスポンスヘッダーとともに拒否されます。
その他のプロキシレベルの失敗(到達不能、タイムアウト、不正なリクエストなど)もすべてを設定するため、docfy-uiはプロキシの失敗をAPIから返る本物の4xx/5xxレスポンスと区別できます。後者はステータス・ヘッダー・ボディをそのまま通過させます。