跳到内容

配置

如何配置

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 将在此 DOM 元素内部放置其用户界面。
domNode不可用Element，如果未提供 dom_id 则必需。HTML DOM 元素，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 初次渲染时模型的显示方式。（用户可以通过单击“模型”和“示例值”链接随时切换给定模型的渲染方式。）
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。控制操作、参数、响应和 Schema 的供应商扩展 (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 无法控制。
宏
参数名称Docker 变量描述
modelPropertyMacro不可用Function。为模型中每个属性设置默认值的函数。接受一个参数 modelPropertyMacro(property)，property 是不可变的。
parameterMacro不可用Function。为参数设置默认值的函数。接受两个参数 parameterMacro(operation, parameter)。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 必须只包含令牌本身，不带 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' } ]
© . All rights reserved.