構成

構成方法

Swagger UIは、4つの場所で構成パラメーターを受け入れます。

優先度が低い順に並べると

  • プロジェクトのルートディレクトリにあるswagger-config.yaml（存在する場合）は、アプリケーションに組み込まれます
  • Swagger UIに引数として渡される構成オブジェクト（SwaggerUI({ ... })）
  • 指定されたconfigUrlからフェッチされた構成ドキュメント
  • URLクエリ文字列でキー/値ペアとして渡される構成項目

パラメーター

名前の中にドットが含まれるパラメーターは、下位パラメーターを整理するために使用される単一の文字列であり、ネストされた構造を示すものではありません。

読みやすくするため、パラメーターはカテゴリ別にグループ化され、アルファベット順にソートされています。

型の表記は次のようにフォーマットされます。

  • String=""は、デフォルト値が""のString型を意味します。
  • String=["a"*, "b", "c", "d"]は、a、b、c、またはdにできるString型を意味し、*はaがデフォルト値であることを示します。
コア
パラメーター名 Docker変数 説明
configUrl CONFIG_URL String。外部構成ドキュメントをフェッチするためのURL。
dom_id DOM_ID String。domNodeが提供されていない場合は必須。SwaggerUIがユーザーインターフェースを配置するDOM要素のID。
domNode 利用不可 Element。dom_idが提供されていない場合は必須。SwaggerUIがユーザーインターフェースを配置するHTML DOM要素。dom_idをオーバーライドします。
spec SPEC Object={}。OpenAPI定義を記述するJavaScriptオブジェクト。使用すると、urlパラメーターは解析されません。これは、手動で生成した定義をホストせずにテストする場合に役立ちます。
url URL String。API定義を指すURL（通常はswagger.jsonまたはswagger.yaml）。urlsまたはspecが使用されている場合は無視されます。
urls URLS Array。Topbarプラグインで使用されるAPI定義オブジェクトの配列（[{url: "<url1>", name: "<name1>"},{url: "<url2>", name: "<name2>"}]）。これを使用してTopbarプラグインが有効になっている場合、urlパラメーターは解析されません。名前とURLはこの配列のすべての項目で一意である必要があります。これらは識別子として使用されるためです。
urls.primaryName URLS_PRIMARY_NAME String。urlsを使用する場合、このサブパラメーターを使用できます。値がurlsで指定された仕様の名前と一致する場合、Swagger UIのロード時に、urlsの最初の仕様をデフォルトとする代わりに、その仕様が表示されます。
queryConfigEnabled QUERY_CONFIG_ENABLED Boolean=false。URL検索パラメーターを介した構成パラメーターのオーバーライドを有効にします。
プラグインシステム

プラグインシステムの詳細については、カスタマイズドキュメントを参照してください。

パラメーター名 Docker変数 説明
layout 利用不可 String="BaseLayout"。Swagger UIのトップレベルのレイアウトとして使用するプラグインシステムを介して利用可能なコンポーネントの名前。
pluginsOptions 利用不可 Object。プラグインの統合と動作を構成するためのJavaScriptオブジェクト（下記参照）。
plugins 利用不可 Array=[]。Swagger UIで使用するプラグイン関数の配列。
presets 利用不可 Array=[SwaggerUI.presets.ApisPreset]。Swagger UIで使用するプリセットの配列。通常、このオプションを使用する場合はApisPresetを含める必要があります。
プラグインオプション
パラメーター名 Docker変数 説明
pluginLoadType 利用不可 String=["legacy", "chain"]。wrapComponentで同じコンポーネントをターゲットにするときに、プラグインの動作を制御します。
- legacy（デフォルト）：最後のプラグインが他のプラグインよりも優先されます
- chain：同じコアコンポーネントをターゲットにする場合にwrapComponentをチェーンし、複数のプラグインが同じコンポーネントをラップできるようにします
表示
パラメーター名 Docker変数 説明
deepLinking DEEP_LINKING Boolean=false。trueに設定すると、タグと操作のディープリンクが有効になります。詳細については、ディープリンクドキュメントを参照してください。
displayOperationId DISPLAY_OPERATION_ID Boolean=false。操作リストでのoperationIdの表示を制御します。デフォルトはfalseです。
defaultModelsExpandDepth DEFAULT_MODELS_EXPAND_DEPTH Number=1。モデルのデフォルトの展開深度（-1に設定するとモデルは完全に非表示になります）。
defaultModelExpandDepth DEFAULT_MODEL_EXPAND_DEPTH Number=1。モデル例セクションでのモデルのデフォルトの展開深度。
defaultModelRendering DEFAULT_MODEL_RENDERING String=["example"*, "model"]。APIが最初にレンダリングされるときにモデルをどのように表示するかを制御します。（ユーザーは、「モデル」と「例の値」のリンクをクリックして、特定のモデルのレンダリングをいつでも切り替えることができます。）
displayRequestDuration DISPLAY_REQUEST_DURATION Boolean=false。「試してみる」リクエストのリクエスト期間（ミリ秒単位）の表示を制御します。
docExpansion DOC_EXPANSION String=["list"*, "full", "none"]。操作とタグのデフォルトの展開設定を制御します。「list」（タグのみを展開）、「full」（タグと操作を展開）、または「none」（何も展開しない）にすることができます。
filter FILTER Boolean=false OR String。設定すると、フィルタリングが有効になります。上部のバーには、表示されるタグ付き操作をフィルタリングするために使用できる編集ボックスが表示されます。Booleanで有効または無効にしたり、文字列で有効にしたりできます。その場合、その文字列をフィルター式として使用してフィルタリングが有効になります。フィルタリングでは、タグ内の任意の場所でフィルター式と大文字と小文字を区別して一致します。
maxDisplayedTags MAX_DISPLAYED_TAGS Number。設定すると、表示されるタグ付き操作の数がこの数以下に制限されます。デフォルトでは、すべての操作が表示されます。
operationsSorter 利用不可 Function=(a => a)。各APIの操作リストにソートを適用します。「alpha」（パスをアルファベット順にソート）、「method」（HTTPメソッドでソート）、または関数（ソート関数の動作についてはArray.prototype.sort()を参照）にすることができます。デフォルトでは、サーバーから変更されていない順序で返されます。
showExtensions SHOW_EXTENSIONS Boolean=false。操作、パラメーター、レスポンス、スキーマのベンダー拡張（x-）フィールドと値の表示を制御します。
showCommonExtensions SHOW_COMMON_EXTENSIONS Boolean=false。パラメーターの拡張（pattern、maxLength、minLength、maximum、minimum）フィールドと値の表示を制御します。
tagsSorter 利用不可 Function=(a => a)。各APIのタグリストにソートを適用します。「alpha」（パスをアルファベット順にソート）または関数（ソート関数の書き方についてはArray.prototype.sort()を参照）にすることができます。各パスで2つのタグ名文字列がソーターに渡されます。デフォルトはSwagger UIによって決定された順序です。
useUnsafeMarkdown USE_UNSAFE_MARKDOWN Boolean=false。有効にすると、サニタイザーは、マークダウン文字列内で宣言されたすべてのHTML要素に対して、style、class、およびdata-*属性をそのままにします。このパラメーターは非推奨であり、4.0.0で削除されます。
onComplete 利用不可 Function=NOOP。Swagger UIが新しく提供された定義のレンダリングを完了したときに通知されるメカニズムを提供します。
syntaxHighlight 利用不可 ペイロードとcURLコマンドの構文強調表示を無効にする場合はfalseに設定します。それ以外の場合は、activateプロパティとthemeプロパティを持つオブジェクトにすることができます。
syntaxHighlight.activate 利用不可 Boolean=true。構文強調表示を有効にするかどうか。
syntaxHighlight.theme 利用不可 String=["agate"*, "arta", "monokai", "nord", "obsidian", "tomorrow-night", "idea"]。Highlight.jsで使用する構文の色付けテーマ。（これらの7つのスタイルのみが利用可能です。）
tryItOutEnabled TRY_IT_OUT_ENABLED Boolean=false。「試してみる」セクションをデフォルトで有効にするかどうかを制御します。
requestSnippetsEnabled 利用不可 Boolean=false。リクエストスニペットセクションを有効にします。無効にすると、レガシーcURLスニペットが使用されます。
requestSnippets 利用不可 
Object={
  generators: {
    curl_bash: {
      title: "cURL (bash)",
      syntax: "bash"
    },
    curl_powershell: {
      title: "cURL (PowerShell)",
      syntax: "powershell"
    },
    curl_cmd: {
      title: "cURL (CMD)",
      syntax: "bash"
    },
  },
  defaultExpanded: true,
  languages: null, 
  // e.g. only show curl bash = ["curl_bash"]
}
これは、requestSnippetsプラグインのデフォルトの構成セクションです。
ネットワーク
パラメーター名 Docker変数 説明
oauth2RedirectUrl OAUTH2_REDIRECT_URL String。OAuth リダイレクト URL。
requestInterceptor 利用不可 Function=(a => a)。関数である必要があります。リモート定義、「試してみる」、および OAuth 2.0 リクエストをインターセプトする関数。1つの引数 `requestInterceptor(request)` を受け取り、変更されたリクエスト、または変更されたリクエストに解決される Promise を返す必要があります。
request.curlOptions 利用不可 Array。設定した場合、curl コマンドで使用可能なコマンドラインオプションの配列である必要があります。これは、`requestInterceptor` 関数内で変更されたリクエストに設定できます。たとえば、`request.curlOptions = ["-g", "--limit-rate 20k"]` のように設定できます。
responseInterceptor 利用不可 Function=(a => a)。関数である必要があります。リモート定義、「試してみる」、および OAuth 2.0 レスポンスをインターセプトする関数。1つの引数 `responseInterceptor(response)` を受け取り、変更されたレスポンス、または変更されたレスポンスに解決される Promise を返す必要があります。
showMutatedRequest SHOW_MUTATED_REQUEST Boolean=true。`true` に設定した場合、`requestInterceptor` から返された変更されたリクエストを使用して UI で curl コマンドを生成します。それ以外の場合は、`requestInterceptor` が適用される前のリクエストが使用されます。
supportedSubmitMethods SUPPORTED_SUBMIT_METHODS Array=["get", "put", "post", "delete", "options", "head", "patch", "trace"]。「試してみる」機能が有効になっている HTTP メソッドのリスト。空の配列にすると、すべての操作で「試してみる」が無効になります。これは、表示される操作をフィルタリングするものではありません。
validatorUrl VALIDATOR_URL String="https://validator.swagger.io/validator" OR null。デフォルトでは、Swagger UI は swagger.io のオンラインバリデーターに対して仕様を検証しようとします。このパラメーターを使用して、ローカルにデプロイされたバリデーター（Validator Badge）など、別のバリデーター URL を設定できます。これを `none`、`127.0.0.1`、または `localhost` のいずれかに設定すると、検証が無効になります。
withCredentials WITH_CREDENTIALS Boolean=false。`true` に設定した場合、ブラウザーによって送信される CORS リクエストで、Fetch 標準で定義されているように、資格情報の受け渡しを有効にします。Swagger UI は現在、クロスドメインで Cookie を設定できないことに注意してください（swagger-js#1163を参照）。その結果、Swagger UI が制御できない、ブラウザーから提供される Cookie（この設定で送信が有効になります）に頼る必要があります。
マクロ
パラメーター名 Docker変数 説明
modelPropertyMacro 利用不可 Function。モデル内の各プロパティにデフォルト値を設定する関数。1つの引数 `modelPropertyMacro(property)` を受け入れます。`property` は不変です。
parameterMacro 利用不可 Function。パラメーターにデフォルト値を設定する関数。2つの引数 `parameterMacro(operation, parameter)` を受け入れます。`operation` と `parameter` はコンテキストのために渡されるオブジェクトであり、どちらも不変のままです。
認証
パラメーター名 Docker変数 説明
persistAuthorization PERSIST_AUTHORIZATION Boolean=false。`true` に設定した場合、認証データが保持され、ブラウザのクローズ/リフレッシュ時に失われません。

インスタンスメソッド

💡 注意してください！これらはパラメーターではなく、メソッドです.

メソッド名 Docker変数 説明
initOAuth oauth2.mdを参照してください (configObj) => void。OAuth サーバーに関する情報を Swagger UI に提供します。詳細については、OAuth 2.0 のドキュメントを参照してください。
preauthorizeBasic 利用不可 (authDefinitionKey, username, password) => action。基本認証スキームの値をプログラムで設定します。
preauthorizeApiKey 利用不可 (authDefinitionKey, apiKeyValue) => action。API キーまたは Bearer 認証スキームの値をプログラムで設定します。OpenAPI 3.0 Bearer スキームの場合、`apiKeyValue` には、`Bearer` プレフィックスなしでトークン自体のみを含める必要があります。

Docker

Docker イメージを使用している場合は、これらのオプションのほとんどを環境変数で制御することもできます。各パラメーターには、利用可能な場合は、環境変数名が記載されています。

以下は、環境変数インターフェースを使用するための一般的なガイドラインです。

文字列変数

必要な場合は文字をエスケープして、任意の値に設定します。

例

FILTER="myFilterValue"
LAYOUT="BaseLayout"
ブール変数

値を `true` または `false` に設定します。

例

DISPLAY_OPERATION_ID="true"
DEEP_LINKING="false"
数値変数

値を *`n`* に設定します。ここで、*n* は提供する数値です。

例

DEFAULT_MODELS_EXPAND_DEPTH="5"
DEFAULT_MODEL_EXPAND_DEPTH="7"
配列変数

必要な場合は文字をエスケープして、任意の配列リテラル値に設定します。

例

SUPPORTED_SUBMIT_METHODS="[\"get\", \"post\"]"
URLS="[ { url: \"https://petstore.swagger.io/v2/swagger.json\", name: \"Petstore\" } ]"
オブジェクト変数

必要な場合は文字をエスケープして、任意のリテラルオブジェクト値に設定します。

例

SPEC="{ \"openapi\": \"3.0.0\" }"

Docker-Compose

.env ファイルのエンコーディング例

SUPPORTED_SUBMIT_METHODS=['get', 'post']
URLS=[ { url: 'https://petstore.swagger.io/v2/swagger.json', name: 'Petstore' } ]