如何修改或禁用 Swagger UI 的在线规范校验徽章validatorUrl【免费下载链接】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-uiSwagger UI 页面右上角默认会显示一枚在线校验徽章它把当前加载的 OpenAPI/Swagger 规范 URL 发给 swagger.io 的在线校验器用一张小图标表示校验是否通过。如果你的环境无法访问该在线服务、想避免把内部规范地址外发或者希望改用自部署的校验器都可以用validatorUrl参数来完成这件事。配置文档对它的定义是validatorUrlStringhttps://validator.swagger.io/validator OR null。By default, Swagger UI attempts to validate specs against swagger.ios online validator. You can use this parameter to set a different validator URL, for example for locally deployed validators. Setting it to eithernone,127.0.0.1orlocalhostwill disable validation.也就是说改成一个新地址即可换校验器取值为none、127.0.0.1或localhost时直接禁用徽章。徽章的渲染逻辑什么时候会显示修改前先了解徽章组件 OnlineValidatorBadge 的行为这决定了修改后应该如何验证效果组件读取配置中的validatorUrl未配置时回落到默认值https://validator.swagger.io/validator只有当规范是通过url从远端加载时才会渲染徽章——如果配置里直接传了非空的spec对象组件直接返回null不显示徽章是否渲染由工具函数 requiresValidationURL 判定当值为空、包含localhost、包含127.0.0.1或等于none时返回false即不校验、不渲染渲染时徽章图片地址为validatorUrl?url编码后的规范 URL整个徽章可点击跳转到validatorUrl/debug?url编码后的规范 URL页面target_blank relnoopener noreferrer。方式一在初始化配置对象中设置validatorUrlvalidatorUrl是普通配置参数直接写进SwaggerUI({ ... })的参数对象即可。改为你自己的校验器地址SwaggerUI({ url: https://petstore3.swagger.io/api/v3/openapi.json, dom_id: #swagger-ui, validatorUrl: https://your-own-validator.example.com/validator // 替换为你部署的校验器根地址 })禁用徽章文档列出的三个取值任选其一SwaggerUI({ url: https://petstore3.swagger.io/api/v3/openapi.json, dom_id: #swagger-ui, validatorUrl: none // 也可以用 localhost 或 127.0.0.1 })注意文档同时标注该参数允许null传入null与取none/localhost/127.0.0.1的效果一致徽章不再请求默认校验器。方式二通过configUrl外部配置文件修改如果 Swagger UI 通过configUrl加载外部配置文档文档中优先级介于初始化参数与 URL 查询参数之间可以在该配置文档中加入同一个validatorUrl键值的使用规则与方式一完全相同无需改动页面里的 JS 代码。方式三通过 URL 查询参数临时覆盖配置文档说明 Swagger UI 接受三个位置的配置优先级从低到高依次是传给SwaggerUI({ ... })的配置对象、configUrl拉取的配置文档、URL 查询字符串中的键值对。URL 查询参数默认不生效需要先在配置对象中开启queryConfigEnabledBooleanfalse文档说明其作用是 Enables overriding configuration parameters via URL search paramsSwaggerUI({ url: https://petstore3.swagger.io/api/v3/openapi.json, dom_id: #swagger-ui, queryConfigEnabled: true })开启后在访问页面的 URL 查询参数中加入validatorUrlnone或其他取值即可覆盖徽章行为适合排查问题或给个别访问入口做临时调整。方式四Docker 部署时用VALIDATOR_URL环境变量使用官方 Docker 镜像时每个配置参数大多有对应的环境变量。docker/configurator/variables.js 中注册了VALIDATOR_URLstring 类型映射到validatorUrl因此可以在docker run中直接传docker run -p 80:8080 -e VALIDATOR_URLnone -e SWAGGER_JSON/foo/swagger.json -v /bar:/foo docker.swagger.io/swaggerapi/swagger-ui上面示例沿用了 安装文档中挂载宿主机规范的写法/foo、/bar是文档示例路径按你的实际目录替换-e VALIDATOR_URLnone是禁用徽章的部分换成校验器地址即改用它。String 类型环境变量按文档说明直接赋值即可必要时转义字符。如何验证修改生效根据 徽章组件的实现 与 单元测试验证点很具体禁用场景把validatorUrl设为none/localhost/127.0.0.1后刷新页面右上角的校验徽章应整体消失组件返回null并且页面不再向校验器发起请求。自定义校验器场景徽章图片的src应指向你的校验器地址?url编码后的规范 URL点击徽章应在新标签页打开你的校验器地址/debug?url...。单元测试给出了默认校验器下的期望值可作为格式参考文档示例链接 hrefhttps://validator.swagger.io/validator/debug?urlhttps%3A%2F%2Fsmartbear.com%2Fswagger.json图片 srchttps://validator.swagger.io/validator?urlhttp%3A%2F%2Fgoogle.com%2Fswagger.json注意一个前置条件如果你是通过spec配置项直接传入规范对象而不是url徽章本来就不会渲染此时无需也不应通过validatorUrl来禁用它。限制与注意事项取值none、localhost、127.0.0.1的禁用判定写在 requiresValidationURL 中是前缀/包含匹配任何包含localhost或127.0.0.1的地址都会被视为禁用如果你的校验器恰好部署在含这些字符串的地址上徽章不会显示。三个配置位置可以共存URL 查询参数优先级最高需queryConfigEnabled: true其次是configUrl文档最低是初始化配置对象同时设置时以高优先级者为准。validatorUrl只影响这枚校验徽章与规范本身的加载、Try it out等功能无关。参数完整定义见 docs/usage/configuration.md 的 Network 参数表Docker 镜像的用法见 docs/usage/installation.md。【免费下载链接】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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考