跳到內容

組態設定

如何組態設定

Swagger UI 接受三個位置的組態設定參數。

優先順序由低到高

  • 作為引數傳遞給 Swagger UI 的組態設定物件 (SwaggerUI({ ... }))
  • 從指定的 configUrl 擷取的組態設定文件
  • 在 URL 查詢字串中作為鍵/值組傳遞的組態設定項目

參數

名稱中帶點的參數是單一字串，用於組織從屬參數，並非表示巢狀結構。

為了方便閱讀，參數會依類別分組並依字母順序排序。

類型標記格式如下

  • String="" 表示字串類型，預設值為 ""。
  • String=["a"*, "b", "c", "d"] 表示字串類型，可以是 a、b、c 或 d，其中 * 表示 a 是預設值。
核心
參數名稱Docker 變數描述
configUrlCONFIG_URLString。從中擷取外部組態設定文件的 URL。
dom_idDOM_IDString，如果未提供 domNode，則為必要。DOM 元素的 ID，SwaggerUI 會將其使用者介面放在其中。
domNode無法使用Element，如果未提供 dom_id，則為必要。HTML DOM 元素，SwaggerUI 會將其使用者介面放在其中。覆寫 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 首次呈現時如何顯示模型。(使用者隨時可以按一下「模型」和「範例值」連結，切換給定模型的呈現方式。)
displayRequestDuration DISPLAY_REQUEST_DURATION Boolean=false。控制「試試看」要求的要求持續時間（以毫秒為單位）的顯示。
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。控制顯示操作、參數、回應和結構描述的供應商擴展 (x-) 欄位和值。
showCommonExtensions SHOW_COMMON_EXTENSIONS Boolean=false。控制顯示參數的擴展 (pattern、maxLength、minLength、maximum、minimum) 欄位和值。
tagsSorter 無法使用 Function=(a => a)。對每個 API 的標籤列表應用排序。它可以是 'alpha'（按路徑字母數字排序）或函數（請參閱 Array.prototype.sort() 了解如何編寫排序函數）。每次傳遞時，都會將兩個標籤名稱字串傳遞給排序器。預設值是 Swagger UI 確定的順序。
useUnsafeMarkdown USE_UNSAFE_MARKDOWN Boolean=false。啟用時，清除器將保留在 markdown 字串內宣告的所有 HTML 元素的 style、class 和 data-* 屬性不受影響。此參數已過時，將在 4.0.0 中移除。
onComplete 無法使用 Function=NOOP。提供一種機制，以便在 Swagger UI 完成轉譯新提供的定義時收到通知。
syntaxHighlight 無法使用 設定為 false 以停用有效負載和 cURL 命令的語法突顯，否則可以是具有 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。控制是否應預設啟用「試試看」區段。
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)。必須是函數。用於攔截遠端定義、「試試看」和 OAuth 2.0 請求的函數。接受一個引數 requestInterceptor(request)，並且必須傳回修改後的請求，或解析為修改後請求的 Promise。
request.curlOptions無法使用Array。如果設定，必須是可供 curl 命令使用的命令列選項陣列。這可以在 requestInterceptor 函數中的已變異請求上設定。例如 request.curlOptions = ["-g", "--limit-rate 20k"]
responseInterceptor無法使用Function=(a => a)。必須是函數。用於攔截遠端定義、「試試看」和 OAuth 2.0 回應的函數。接受一個引數 responseInterceptor(response)，並且必須傳回修改後的回應，或解析為修改後回應的 Promise。
showMutatedRequestSHOW_MUTATED_REQUESTBoolean=true。如果設定為 true，則會使用從 requestInterceptor 傳回的變異請求，在 UI 中產生 curl 命令，否則會使用套用 requestInterceptor 前的請求。
supportedSubmitMethodsSUPPORTED_SUBMIT_METHODSArray=["get", "put", "post", "delete", "options", "head", "patch", "trace"]。已啟用「試試看」功能的 HTTP 方法清單。空陣列會停用所有操作的「試試看」。這不會從顯示中篩選操作。
validatorUrlVALIDATOR_URLString="https://validator.swagger.io/validator" OR null。預設情況下，Swagger UI 會嘗試根據 swagger.io 的線上驗證器驗證規格。您可以使用此參數設定不同的驗證器 URL，例如用於本機部署的驗證器（驗證器徽章）。將其設定為 none、127.0.0.1 或 localhost 將會停用驗證。
withCredentialsWITH_CREDENTIALSBoolean=false 如果設定為 true，則啟用在瀏覽器傳送的 CORS 請求中傳遞憑證，如 Fetch 標準中所定義。請注意，Swagger UI 目前無法跨網域設定 Cookie（請參閱 swagger-js#1163） - 因此，您必須依賴瀏覽器提供的 Cookie（此設定允許傳送），Swagger UI 無法控制這些 Cookie。
巨集
參數名稱Docker 變數描述
modelPropertyMacro無法使用Function。用於設定模型中每個屬性預設值的函數。接受一個引數 modelPropertyMacro(property)，屬性是不可變的
parameterMacro無法使用Function。用於設定參數預設值的函數。接受兩個引數 parameterMacro(operation, parameter)。傳遞操作和參數物件以取得內容，兩者都保持不可變
授權
參數名稱Docker 變數描述
persistAuthorizationPERSIST_AUTHORIZATIONBoolean=false。如果設定為 true，它會持續授權資料，並且不會在瀏覽器關閉/重新整理時遺失

執行個體方法

💡 請注意！這些是方法，而不是參數.

方法名稱Docker 變數描述
initOAuth請參閱 oauth2.md(configObj) => void。向 Swagger UI 提供有關您 OAuth 伺服器的資訊 - 如需詳細資訊，請參閱 OAuth 2.0 文件。
preauthorizeBasic無法使用(authDefinitionKey, username, password) => action。以程式方式設定基本授權方案的值。
preauthorizeApiKey無法使用(authDefinitionKey, apiKeyValue) => action。以程式方式設定 API 金鑰或 Bearer 授權方案的值。對於 OpenAPI 3.0 Bearer 方案，apiKeyValue 必須僅包含 Token 本身，不包含 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.0\" }"

Docker-Compose

.env 檔案範例編碼

終端機視窗
1
SUPPORTED_SUBMIT_METHODS=['get', 'post']
2
URLS=[ { url: 'https://petstore.swagger.io/v2/swagger.json', name: 'Petstore' } ]
Swagger 開源
Swagger
專業工具
資源