Try it out

使い方

すべてのエンドポイントのリクエストパネルには、言語タブの隣にCode / Try it outのモード切り替えがあります。Try it outは編集可能なフォーム(ベースURL、パス/クエリ/ヘッダーパラメータ、リクエストボディ)で、executeRequest()経由で実際のリクエストを実行し、宣言済みのサンプルレスポンスと並んでLiveタブに結果を表示します(ボディがJSONの場合は整形表示され、ネットワーク/CORS障害時は生のエラーの代わりに分かりやすいメッセージが表示されます)。ベースURLはデフォルトでOpenAPIドキュメントのservers[]配列の最初のエントリー(存在する場合)になりますが、常に自由に編集できます。

認証

security要件があるエンドポイントには、宣言済みのスキームごとに1つの入力欄を持つインライン認証フォームが表示されます。

• apiKey: 宣言された場所(ヘッダーまたはクエリパラメータ)に応じて送信されます。
• http bearer / OAuth2 / OpenID Connect: いずれも直接貼り付けたトークンを受け付けます。OAuthフローの実行はありません。
• http basic: user:passの形式を想定します。

認証情報はグローバルです(実際の開発用トークンと同じように、そのスキームを使うすべてのエンドポイントで共有されます)。localStorageに保存されるため、リロードしても保持されます。

成功したLiveレスポンスにトークンらしきフィールドが含まれる場合(例えばログインエンドポイントのaccess_tokenで、data.access_tokenのようなエンベロープの中にネストされたものも含みます)、「Use as … token」ボタンでセッションの残りの認証情報として手動でコピー&ペーストすることなく再利用できます。

同一オリジンプロキシ

デフォルトでは、Try it outはブラウザから対象APIへの直接のfetch()であり、そのAPI自身のCORSポリシーに従います。nestjs-docfyのDocfyUiModule.setup()(API referenceを参照)がOpenAPIドキュメントとともに設定されている場合、docfy-uiは注入されたwindow.__DOCFY_PROXY_PATH__グローバルを検出し、代わりに同一オリジンのサーバーサイドプロキシ経由でリクエストをルーティングします。これによりCORSは一切適用されません。

プロキシの許可リストは、ドキュメントのservers[]配列にある絶対URLだけから構築されます。クライアントが制御するヘッダーに依存することになるため、暗黙の「このリクエストと同一オリジン」というフォールバックはありません。許可されていないオリジンへのリクエスト、またはプロキシ自体でのその他の失敗は、X-Docfy-Proxy-Errorレスポンスヘッダーとともに返されます。これによりdocfy-uiはプロキシレベルの失敗をAPIからの本物のレスポンスと区別できます。