跳到内容

配置

如何配置

Swagger UI 接受三个位置的配置参数。

从最低到最高的优先级

  • 作为参数传递给 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，则为必需。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。如果设置，则启用筛选。顶部栏将显示一个编辑框，您可以使用该框来筛选显示的已标记操作。可以是 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() 以了解如何编写排序函数）。每次遍历时，都会将两个标签名称字符串传递给排序器。默认情况下，排序顺序由 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。控制默认情况下是否应启用“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)，并且必须返回修改后的请求，或解析为修改后的请求的 Promise。
request.curlOptions不可用Array。如果设置，则必须是可用于 curl 命令的命令行选项的数组。可以在 requestInterceptor 函数中修改的请求上设置此项。例如，request.curlOptions = ["-g", "--limit-rate 20k"]
responseInterceptor不可用Function=(a => a)。必须是一个函数。用于拦截远程定义、“Try it out”和 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"]。启用了“Try it out”功能的 HTTP 方法列表。空数组会禁用所有操作的“Try it out”。这不会从显示中过滤操作。
validatorUrlVALIDATOR_URLString="https://validator.swagger.io/validator" OR null。默认情况下，Swagger UI 尝试根据 swagger.io 的在线验证器验证规范。您可以使用此参数设置不同的验证器 URL，例如用于本地部署的验证器 (Validator Badge)。将其设置为 none、127.0.0.1 或 localhost 将禁用验证。
withCredentialsWITH_CREDENTIALSBoolean=false 如果设置为 true，则启用在浏览器发送的 CORS 请求中传递凭据，如 Fetch 标准中所定义。请注意，Swagger UI 目前无法设置跨域 Cookie（请参阅 swagger-js#1163） - 因此，您必须依赖浏览器提供的 Swagger UI 无法控制的 Cookie（此设置启用发送）。
宏
参数名称Docker 变量描述
modelPropertyMacro不可用Function。用于为模型中的每个属性设置默认值的函数。接受一个参数 modelPropertyMacro(property)，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 必须仅包含令牌本身，而不包含 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
专业工具
资源