Swagger UI 配置完全指南：三大配置来源、全部参数详解与 Docker 环境变量实践-迪斯科星球

Swagger UI 配置完全指南：三大配置来源、全部参数详解与 Docker 环境变量实践

【免费下载链接】swagger-uiSwagger UI is a collection of HTML, JavaScript, and CSS assets that dynamically generate beautiful documentation from a Swagger-compliant API.项目地址: https://gitcode.com/GitHub_Trending/sw/swagger-ui

本文档是 Swagger UI 配置体系的技术指南，完整覆盖配置参数注入的三大来源与优先级规则、Core/插件系统/Display/Network/Macros/Authorization 六大类全部配置参数、实例方法以及 Docker 环境变量与 Docker-Compose 的实战用法。读完本文，你将能够熟练地以配置对象、远端配置文件或 URL 查询参数三种方式定制 Swagger UI，并掌握每个参数的类型、默认值与底层解析机制，从而精确控制文档渲染、调试、鉴权与网络行为。

一、配置的三大来源与优先级

Swagger UI 接受配置参数的渠道共有三处，按优先级从低到高排列：

配置对象：作为参数传入SwaggerUI({ ... })的 JavaScript 配置对象（优先级最低）；
远端配置文件：通过configUrl参数指定的地址获取的外部配置文件；
URL 查询参数：以 key/value 形式携带在页面 URL 查询字符串中的配置项（优先级最高）。

从源码结构看，这一优先级模型由 src/core/config/index.js 统一导出并实现：

query.js 负责从 URL 查询字符串读取选项。值得注意的是，只有当queryConfigEnabled为true时，查询字符串才会被解析；同时它保留了向后兼容逻辑——查询参数config会被映射为configUrl，而urls.primaryName会被原样保留（因为它是挂在数组实例上的任意属性，不能走普通的嵌套set路径）；
url.js 负责从configUrl拉取远端配置，它依赖system.configsActions.getConfigByUrl以loadRemoteConfig: true的方式异步加载，并会把用户的requestInterceptor/responseInterceptor一并传递给远端请求；远端获取失败时返回null，不会阻塞系统启动；
runtime.js 在运行时自动注入与当前页面位置相关的选项——例如基于globalThis.location推导出默认的oauth2RedirectUrl，指向同目录下的oauth2-redirect.html。

三个来源最终通过 merge.js 按顺序合并：先合并运行时注入与默认值，再叠加配置对象、远端配置，最后以查询参数覆盖。合并层面对domNode与urls.primaryName做了特殊处理（从deep-extend的破坏性合并中剥离，再在合并完成后回填），因为domNode是 DOM 元素无法被深拷贝，而urls.primaryName是数组上的自定义属性。

参数命名约定与类型记号

参数名中的点（.）仅用于组织从属参数，是单个字符串，并不表示嵌套结构。例如urls.primaryName、syntaxHighlight.activated在合并与类型转换时都以扁平 key 处理（见 type-cast/mappings.js 中"syntaxHighlight.activated"这类带点键名）。

类型记号约定如下：

String=""：String 类型，默认值为""；
String=["a"*, "b", "c", "d"]：String 类型，可选值为a、b、c或d，其中*标记的a是默认值。

二、Core 核心参数

参数名	Docker 环境变量	说明
`configUrl`	`CONFIG_URL`	`String`。拉取外部配置文档的 URL。
`dom_id`	`DOM_ID`	`String`，在未提供`domNode`时为必填。SwaggerUI 将用户界面渲染进该 ID 对应的 DOM 元素。
`domNode`	不可用	`Element`，在未提供`dom_id`时为必填。SwaggerUI 渲染进该 HTML DOM 元素，优先级高于`dom_id`。
`spec`	`SPEC`	`Object={}`。描述 OpenAPI 定义的 JavaScript 对象。使用后`url`参数将不再被解析，适合为手工生成的、未托管的定义做本地测试。
`url`	`URL`	`String`。指向 API 定义（通常为`swagger.json`或`swagger.yaml`）的 URL。当使用了`urls`或`spec`时被忽略。
`urls`	`URLS`	`Array`。API 定义对象数组（`[{url: "<url1>", name: "<name1>"}, {url: "<url2>", name: "<name2>"}]`），供 Topbar 插件使用。启用 Topbar 插件时`url`参数将不再被解析。数组内所有 name 与 url 必须唯一，因为它们被用作标识符。
`urls.primaryName`	`URLS_PRIMARY_NAME`	`String`。使用`urls`时的子参数。若该值匹配`urls`中某个定义的 name，则 Swagger UI 加载时直接显示该定义，而不是默认显示`urls`中的第一项。
`queryConfigEnabled`	`QUERY_CONFIG_ENABLED`	`Boolean=false`。启用后允许通过 URL 查询参数覆盖配置项。

核心参数之间的取舍关系值得注意：spec、url、urls三者互斥，其优先级与默认值定义在 src/core/config/defaults.js（url: ""、urls: null、spec: {}）。从 merge.js 与 system.js 的源码可见，url会被注入spec.url供 spec 插件加载，spec则直接进入 spec state；urls.primaryName在合并阶段被剥离后作为数组自定义属性回填，供 Topbar 插件在加载时选中对应定义。

三、Plugin system 插件系统参数

关于插件系统的完整原理，可阅读 Customization 文档。

参数名	Docker 环境变量	说明
`layout`	不可用	`String="BaseLayout"`。通过插件系统可用的组件名，用作 Swagger UI 的顶层布局。
`plugins`	不可用	`Array=[]`。要使用的插件函数数组。
`presets`	不可用	`Array=[SwaggerUI.presets.ApisPreset]`。要使用的预设数组。通常使用本参数时建议包含`ApisPreset`。

从源码实现看，system.js 会把options.presets直接展开为plugins送入系统，而 inline-plugin.js 将options.fn与options.components合成一个内联插件，从而支持以配置对象直接注入自定义组件与工具函数。默认预设ApisPreset定义于 src/core/presets/apis/index.js，它聚合了 base 布局插件、core-components 与 form-components 等基础能力（见 src/core/presets/base/index.js）。

四、Display 显示参数

参数名	Docker 环境变量	说明
`deepLinking`	`DEEP_LINKING`	`Boolean=false`。设为`true`时为 tag 与 operation 启用深链接。详见 Deep Linking 文档。
`displayOperationId`	`DISPLAY_OPERATION_ID`	`Boolean=false`。控制操作列表中是否显示 operationId，默认`false`。
`defaultModelsExpandDepth`	`DEFAULT_MODELS_EXPAND_DEPTH`	`Number=1`。模型（models）区域的默认展开深度，设为`-1`可完全隐藏模型区。
`defaultModelExpandDepth`	`DEFAULT_MODEL_EXPAND_DEPTH`	`Number=1`。model-example 区域中单个模型的默认展开深度。
`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"]`。控制操作与 tag 的默认展开状态：`list`（只展开 tag）、`full`（展开 tag 与操作）、`none`（全部折叠）。
`filter`	`FILTER`	`Boolean=false OR String`。启用后顶栏显示过滤输入框，用于过滤展示的 tagged operations。可传 Boolean 开关，或传字符串作为过滤表达式。过滤为大小写敏感匹配，在 tag 内部任意位置命中即显示。
`maxDisplayedTags`	`MAX_DISPLAYED_TAGS`	`Number`。设置后最多展示该数量的 tagged operations，默认展示全部。
`operationsSorter`	不可用	`Function=(a => a)`。对每个 API 的操作列表应用排序。可为`'alpha'`（按路径字母序）、`'method'`（按 HTTP 方法）或排序函数（参考`Array.prototype.sort()`的规则）。默认保持服务端返回顺序不变。
`showExtensions`	`SHOW_EXTENSIONS`	`Boolean=false`。控制 Operation、Parameter、Response、Schema 上供应商扩展字段（`x-`前缀）及值的显示。
`showCommonExtensions`	`SHOW_COMMON_EXTENSIONS`	`Boolean=false`。控制 Parameter 的通用扩展字段（`pattern`、`maxLength`、`minLength`、`maximum`、`minimum`）及值的显示。
`tagsSorter`	不可用	`Function=(a => a)`。对每个 API 的 tag 列表应用排序。可为`'alpha'`（按路径字母序）或排序函数，每次排序会传入两个 tag 名字符串。默认采用 Swagger UI 确定的顺序。
`useUnsafeMarkdown`	`USE_UNSAFE_MARKDOWN`	`Boolean=false`。启用后，消毒器将保留 markdown 字符串内所有 HTML 元素上的`style`、`class`与`data-`属性。已废弃*，将在`4.0.0`移除。
`onComplete`	不可用	`Function=NOOP`。当 Swagger UI 完成对新提供定义的渲染时被通知的机制。
`syntaxHighlight`	不可用	设为`false`可关闭 payload 与 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`。启用请求代码片段（request snippet）区域。关闭时使用旧版 cURL 片段。
`requestSnippets`	不可用	`Object`，requestSnippets 插件的默认配置段，默认值如下。

requestSnippets的完整默认配置结构：

{ 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"] }

即默认提供 bash、PowerShell、CMD 三种 cURL 生成器；defaultExpanded: true表示代码片段默认展开；languages: null表示展示全部生成器，若只想显示某几种，可设为如["curl_bash"]。该配置对象在 defaults.js 中被冻结为默认值，并由syntaxHighlight类型转换器做对象级兜底（见 type-cast/mappings.js）。

从测试角度，上述显示类参数大多有对应的单元与端到端用例可验证行为，例如 test/e2e-cypress/e2e/features/syntax-highlighting-json.cy.js 与 test/e2e-cypress/e2e/features/schema-form.cy.js，可结合阅读以理解各参数的实际渲染效果。

五、Network 网络参数

参数名	Docker 环境变量	说明
`oauth2RedirectUrl`	`OAUTH2_REDIRECT_URL`	`String`。OAuth 重定向 URL。
`requestInterceptor`	不可用	`Function=(a => a)`。必须为函数。用于拦截远端定义、 “Try it out” 与 OAuth 2.0 请求。接收一个参数`requestInterceptor(request)`，必须返回修改后的请求，或解析为修改后请求的 Promise。
`request.curlOptions`	不可用	`Array`。设置后必须是`curl`命令可用命令行选项的数组。可在`requestInterceptor`中对被修改的 request 设置，例如`request.curlOptions = ["-g", "--limit-rate 20k"]`。
`responseInterceptor`	不可用	`Function=(a => a)`。必须为函数。用于拦截远端定义、 “Try it out” 与 OAuth 2.0 响应。接收一个参数`responseInterceptor(response)`，必须返回修改后的响应，或解析为修改后响应的 Promise。
`showMutatedRequest`	`SHOW_MUTATED_REQUEST`	`Boolean=true`。设为`true`时，界面中的 cURL 命令使用`requestInterceptor`返回的修改后请求；否则使用拦截前的原始请求。
`supportedSubmitMethods`	`SUPPORTED_SUBMIT_METHODS`	`Array=["get", "put", "post", "delete", "options", "head", "patch", "trace"]`。启用 “Try it out” 的 HTTP 方法列表。空数组将禁用所有操作的 “Try it out”，但不会从展示中过滤这些操作。
`validatorUrl`	`VALIDATOR_URL`	`String="https://validator.swagger.io/validator" OR null`。默认 Swagger UI 会尝试用 swagger.io 的在线校验器校验 spec；可改用其他校验器地址（例如本地部署的 Validator Badge）。设为`none`、`127.0.0.1`或`localhost`将禁用校验。
`withCredentials`	`WITH_CREDENTIALS`	`Boolean=false`。设为`true`时，浏览器发出的 CORS 请求会携带凭证（按 Fetch 标准中 credentials 的定义）。注意 Swagger UI 目前无法跨域设置 cookie，只能依赖浏览器自带的 cookie（该设置负责允许发送这些 cookie），Swagger UI 无法控制 cookie 内容。

从实现细节看，defaults.js 中requestInterceptor的默认实现会为每个请求注入空数组request.curlOptions = []；supportedSubmitMethods默认覆盖全部 8 种 HTTP 方法；validatorUrl默认指向 swagger.io 在线校验器。上述函数类参数在 type-cast/mappings.js 中由functionTypeCaster强制转换为函数，若传入非函数值会被替换为默认值。

六、Macros 宏参数

参数名	Docker 环境变量	说明
`modelPropertyMacro`	不可用	`Function`。为模型中的每个属性设置默认值。接收一个参数`modelPropertyMacro(property)`，`property`不可变。
`parameterMacro`	不可用	`Function`。为参数设置默认值。接收两个参数`parameterMacro(operation, parameter)`，`operation`与`parameter`均为只读上下文对象。

这两个宏在类型转换中对应nullableFunctionTypeCaster，允许为null/undefined，此时表示不启用宏逻辑。

七、Authorization 授权参数

参数名	Docker 环境变量	说明
`persistAuthorization`	`PERSIST_AUTHORIZATION`	`Boolean=false`。设为`true`后，授权数据会被持久化，浏览器关闭或刷新后不会丢失。

八、实例方法（Instance methods）

请注意：以下是方法（methods），不是参数（parameters）。

方法名	Docker 环境变量	说明
`initOAuth`	参见 oauth2.md	`(configObj) => void`。向 Swagger UI 提供 OAuth 服务器信息，详见 OAuth 2.0 文档。
`preauthorizeBasic`	不可用	`(authDefinitionKey, username, password) => action`。以编程方式为 Basic 授权方案设置值。
`preauthorizeApiKey`	不可用	`(authDefinitionKey, apiKeyValue) => action`。以编程方式为 API key 或 Bearer 授权方案设置值。对 OpenAPI 3.0 Bearer 方案，`apiKeyValue`只需传 token 本身，不要加`Bearer`前缀。

preauthorizeBasic与preauthorizeApiKey返回的是可派发的 action，可与 auth 插件的 reducer/selector 配合使用（相关实现见 src/core/plugins/auth/index.js 及同目录下的 actions.js）。

九、Docker 环境变量配置

使用官方 Docker 镜像时，上述参数大多可通过同名环境变量控制——每个参数是否支持已在上文各表格的 “Docker variable” 列标注。以下为环境变量接口的通用使用准则。

字符串变量（String variables）

设置为任意字符串，注意按需转义特殊字符：

FILTER="myFilterValue" LAYOUT="BaseLayout"

布尔变量（Boolean variables）

设置为true或false：

DISPLAY_OPERATION_ID="true" DEEP_LINKING="false"

数字变量（Number variables）

设置为n，其中n是你想提供的数字：

DEFAULT_MODELS_EXPAND_DEPTH="5" DEFAULT_MODEL_EXPAND_DEPTH="7"

数组变量（Array variables）

设置为字面量数组值，注意按需转义字符：

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

对象变量（Object variables）

设置为字面量对象值，注意按需转义字符：

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

Docker 侧的环境变量到 UI 配置的转换由 docker/configurator 目录下的脚本完成：其中 translator.js 负责把环境变量翻译为配置结构，variables.js 定义各变量的默认值与合法取值，helpers.js 提供类型转换辅助，index.js 为入口；容器启动时由 40-swagger-ui.sh 调用该配置器生成最终配置。相关逻辑在 test/unit/docker/translator.js 与 test/unit/docker/oauth.js 中有对应单元测试。

十、Docker-Compose 的 .env 编码示例

在使用 Docker-Compose 时，可将上述环境变量写入.env文件，示例编码如下（注意此处使用单引号包裹字符串）：

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

十一、配置管线的底层实现：默认值、合并与类型转换

理解了参数清单之后，再俯瞰整条配置管线会更有把握。Swagger UI 的配置处理在 src/core/config 中分四步完成：

默认值：所有参数默认值集中定义在 src/core/config/defaults.js，并使用Object.freeze冻结，防止运行时被意外篡改；
来源收集：三个来源（query.js、url.js、runtime.js）分别产出各自的选项对象；
合并：merge.js 使用deep-extend按优先级叠加，并特殊保护domNode与urls.primaryName两个无法常规深合并的值；
类型转换：type-cast/index.js 依据 type-cast/mappings.js 的映射表逐项做类型强制（如布尔、数字、数组、函数、排序器、语法高亮对象等），确保无论配置来自对象、远端文件还是 URL 查询串，最终都以正确类型进入系统——这也是为什么?docExpansion=full这样的查询参数能安全覆盖默认值的原因。

该类型转换管线有独立的单元测试可印证，见 test/unit/core/config/type-cast/ 目录。

十二、配置实战：三种方式组合使用

综合以上内容，给出一个组合配置的完整示例。假设你的页面 URL 为https://example.com/swagger-ui/?urls.primaryName=Petstore，同时queryConfigEnabled已启用：

// 方式一：构造时传入配置对象（优先级最低，会被下面两者覆盖） const ui = SwaggerUI({ dom_id: "#swagger-ui", urls: [ { url: "https://petstore.swagger.io/v2/swagger.json", name: "Petstore" }, { url: "https://example.com/api/openapi.yaml", name: "Internal" } ], urls: { primaryName: "Internal" }, // 注意：urls.primaryName 为数组自定义属性 docExpansion: "list", deepLinking: true, presets: [SwaggerUI.presets.ApisPreset], plugins: [], filter: "store", supportedSubmitMethods: ["get", "post"], persistAuthorization: true, requestInterceptor: (req) => { req.headers["X-Client"] = "swagger-ui-demo"; req.curlOptions = ["-g", "--limit-rate 20k"]; return req; } }); // 方式二：调用实例方法完成 OAuth 与预授权 ui.initOAuth({ clientId: "your-client-id", appName: "Your App", scopeSeparator: " ", usePkceWithAuthorizationCodeGrant: true }); ui.preauthorizeApiKey("apiKeyAuth", "demo-token");

若希望远端配置文件参与，可在configUrl指向的 JSON 中放置同样的 key/value 集合；若希望 URL 查询参数参与，则如 query.js 所示启用queryConfigEnabled后，?docExpansion=full&filter=pets即会以最高优先级覆盖前两者的取值。按此方式组合，即可在“默认行为—部署定制—运行时临时调整”三个层次上灵活驾驭 Swagger UI 的展示与行为。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

企业官网建设流程全解析