設定

このUIにはビルド時の設定がありません。描画するスペックの解決は、1つのルールと1つの上書き手段で完全に実行時に行われます。

1つのルールと1つの上書き

SourceWhenExample
GET /api-jsonデフォルト: @nestjs/swaggerのSwaggerModule.setup()がSwagger UIと並べて公開するものと一致しますhttps://api.example.com/docs → fetches https://api.example.com/api-json
?spec=<url>クエリパラメータ: 存在する場合はデフォルトより優先されますhttps://docs.example.com/?spec=https://api.example.com/api-json

異なるオリジン間のCORS

UIがAPIと異なるオリジンで配信されている場合は、?spec=による上書きを使い、そのオリジンがGETでJSONドキュメントを取得できるようAPI側のCORS設定を確認してください。

この同一オリジンの問題は、リクエスト実行の際にも再び登場します。そのプロキシがAPI自身の設定に触れることなくCORSを回避する仕組みについてはTry it outを参照してください。

複数スペック

specsをDocfyUiModule.setup()に渡すと、UIを離れることなく複数のOpenAPIドキュメントを切り替えられます。1つのdocfy-uiインスタンスで複数のサービスをカバーしたい場合に便利です。

main.ts
DocfyUiModule.setup('/docs', app, {
  specs: [
    { name: 'Users service', url: 'https://users.example.com/api-json' },
    { name: 'Orders service', url: 'https://orders.example.com/api-json' },
  ],
});

各urlは、デフォルトの/api-jsonスペックとまったく同じようにクライアント側で取得されます(同一オリジンかどうかにかかわらず、そのオリジンのCORSポリシーに従います)。ドロップダウンは2つ以上のスペックが設定されている場合にのみサイドバーに表示されます。specsを省略すればdocfy-uiは以前とまったく同じように動作し、切り替えUIは描画されません。