コンテンツにスキップ

設定

設定方法

Swagger UI は、3 つの場所で設定パラメータを受け入れます。

優先順位は低いものから高いものへ

  • Swagger UI に引数として渡される設定オブジェクト（SwaggerUI({ ... })）
  • 指定された configUrl から取得される設定ドキュメント
  • URL クエリ文字列にキー/値のペアとして渡される設定項目

パラメータ

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

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

タイプ表記は次のようにフォーマットされます

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

プラグインシステムの詳細はカスタマイズドキュメントでご確認ください。

パラメータ名Docker 変数説明
layout利用不可String="BaseLayout"。Swagger UI のトップレベルレイアウトとして使用する、プラグインシステムを介して利用可能なコンポーネントの名前。
plugins利用不可Array=[]。Swagger UI で使用するプラグイン関数の配列。
presets利用不可Array=[SwaggerUI.presets.ApisPreset]。Swagger UI で使用するプリセットの配列。通常、このオプションを使用する場合は ApisPreset を含めることをお勧めします。
表示
パラメータ名 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 が最初にレンダリングされたときにモデルがどのように表示されるかを制御します。（ユーザーは「Model」と「Example Value」のリンクをクリックすることで、特定のモデルのレンダリングをいつでも切り替えることができます。）
displayRequestDuration DISPLAY_REQUEST_DURATION Boolean=false。「Try it out」リクエストの要求期間（ミリ秒単位）の表示を制御します。
docExpansion DOC_EXPANSION String=["list"*, "full", "none"]。操作とタグのデフォルトの展開設定を制御します。「list」（タグのみを展開）、「full」（タグと操作を展開）、または「none」（何も展開しない）のいずれかです。
filter FILTER Boolean=false OR String。設定すると、フィルタリングが有効になります。上部のバーに編集ボックスが表示され、表示されるタグ付き操作をフィルタリングするために使用できます。有効または無効にするブール値、または文字列にすることができ、その場合、その文字列をフィルタリング式として使用してフィルタリングが有効になります。フィルタリングは、タグ内の任意の場所でフィルタリング式と一致する大文字と小文字を区別します。
maxDisplayedTags MAX_DISPLAYED_TAGS Number。設定されている場合、表示されるタグ付き操作の数を最大この数に制限します。デフォルトではすべての操作が表示されます。
operationsSorter 利用不可 Function=(a => a)。各 API の操作リストにソートを適用します。「alpha」（パスでアルファベット順にソート）、「method」（HTTP メソッドでソート）、または関数（ソート関数の動作については Array.prototype.sort() を参照）を指定できます。デフォルトは、サーバーによって返される順序が変更されないままです。
showExtensions SHOW_EXTENSIONS Boolean=false。Operations、Parameters、Responses、および Schema のベンダー拡張子（x-）フィールドと値の表示を制御します。
showCommonExtensions SHOW_COMMON_EXTENSIONS Boolean=false。Parameters の拡張機能（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。新しく提供された定義のレンダリングが完了したときに通知されるメカニズムを提供します。
syntaxHighlight 利用不可 ペイロードと cURL コマンドの構文強調表示を無効にするには false に設定し、それ以外の場合は activated と theme プロパティを持つオブジェクトに設定できます。
syntaxHighlight.activated 利用不可 Boolean=true。構文強調表示をアクティブにするかどうか。
syntaxHighlight.theme 利用不可 String=["agate"*, "arta", "monokai", "nord", "obsidian", "tomorrow-night", "idea"]。Highlight.js 構文カラーリングテーマを使用します。（これらの7つのスタイルのみが利用可能です。）
tryItOutEnabled TRY_IT_OUT_ENABLED Boolean=false。「Try it out」セクションをデフォルトで有効にするかどうかを制御します。
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 変数説明
oauth2RedirectUrlOAUTH2_REDIRECT_URLString。OAuth リダイレクト URL。
requestInterceptor利用不可Function=(a => a)。関数である必要があります。リモート定義、「Try it out」、および OAuth 2.0 リクエストをインターセプトする関数です。引数 requestInterceptor(request) を1つ受け入れ、変更されたリクエスト、または変更されたリクエストに解決される Promise を返さなければなりません。
request.curlOptions利用不可Array。設定されている場合、curl コマンドで使用可能なコマンドラインオプションの配列である必要があります。これは、requestInterceptor 関数で変更されたリクエストに設定できます。例：request.curlOptions = ["-g", "--limit-rate 20k"]
responseInterceptor利用不可Function=(a => a)。関数である必要があります。リモート定義、「Try it out」、および OAuth 2.0 レスポンスをインターセプトする関数です。引数 responseInterceptor(response) を1つ受け入れ、変更されたレスポンス、または変更されたレスポンスに解決される Promise を返さなければなりません。
showMutatedRequestSHOW_MUTATED_REQUESTBoolean=true。true に設定すると、requestInterceptor から返された変更されたリクエストを使用して UI に curl コマンドを生成し、そうでない場合は requestInterceptor が適用される前のリクエストが使用されます。
supportedSubmitMethodsSUPPORTED_SUBMIT_METHODSArray=["get", "put", "post", "delete", "options", "head", "patch", "trace"]。「Try it out」機能が有効になっている HTTP メソッドのリスト。空の配列は、すべての操作の「Try it out」を無効にします。これは、表示から操作をフィルタリングするものではありません。
validatorUrlVALIDATOR_URLString="https://validator.swagger.io/validator" OR null。デフォルトでは、Swagger UI は swagger.io のオンラインバリデーターに対して仕様を検証しようとします。このパラメータを使用して、たとえばローカルにデプロイされたバリデーター（Validator Badge）など、別のバリデーター URL を設定できます。none、127.0.0.1、または localhost のいずれかに設定すると、検証が無効になります。
withCredentialsWITH_CREDENTIALSBoolean=false。true に設定すると、ブラウザによって送信される CORS リクエストで、Fetch 標準で定義されているように、資格情報の送信が有効になります。Swagger UI は現在クロスドメインでクッキーを設定できないことに注意してください（swagger-js#1163を参照）- その結果、Swagger UI が制御できないブラウザ提供のクッキー（この設定で送信が有効になる）に依存する必要があります。
マクロ
パラメータ名Docker 変数説明
modelPropertyMacro利用不可Function。モデル内の各プロパティにデフォルト値を設定する関数。引数を1つ受け入れます modelPropertyMacro(property)、property は不変です。
parameterMacro利用不可Function。パラメータにデフォルト値を設定する関数。引数を2つ受け入れます parameterMacro(operation, parameter)。operation と parameter はコンテキストとして渡されるオブジェクトで、どちらも不変です。
認証
パラメータ名Docker 変数説明
persistAuthorizationPERSIST_AUTHORIZATIONBoolean=false。true に設定すると、認証データが永続化され、ブラウザの終了/更新時に失われることはありません。

インスタンスメソッド

💡 注意！これらはメソッドであり、パラメータではありません.

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

Docker

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

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

文字列変数

必要に応じて文字をエスケープすることに注意しながら、好きな文字列に値を設定します

例

ターミナルウィンドウ
1
FILTER="myFilterValue"
2
LAYOUT="BaseLayout"
ブール変数

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

例

ターミナルウィンドウ
1
DISPLAY_OPERATION_ID="true"
2
DEEP_LINKING="false"
数値変数

値を _n_ に設定します。ここで _n_ は指定したい数値です。

例

ターミナルウィンドウ
1
DEFAULT_MODELS_EXPAND_DEPTH="5"
2
DEFAULT_MODEL_EXPAND_DEPTH="7"
配列変数

必要に応じて文字をエスケープすることに注意しながら、目的の配列リテラル値に値を設定します。

例

ターミナルウィンドウ
1
SUPPORTED_SUBMIT_METHODS="[\"get\", \"post\"]"
2
URLS="[ { url: \"https://petstore.swagger.io/v2/swagger.json\", name: \"Petstore\" } ]"
オブジェクト変数

必要に応じて文字をエスケープすることに注意しながら、目的のオブジェクトリテラル値に値を設定します。

例

ターミナルウィンドウ
1
SPEC="{ \"openapi\": \"3.0.4\" }"

Docker-Compose

.env ファイルのエンコード例

ターミナルウィンドウ
1
SUPPORTED_SUBMIT_METHODS=['get', 'post']
2
URLS=[ { url: 'https://petstore.swagger.io/v2/swagger.json', name: 'Petstore' } ]
© . This site is unofficial and not affiliated with Swagger.