适用范围与准备

适用于已获准访问的 Swagger UI 页面能加载,但定义文件报错,或文档显示正常而 Try it out 失败。先记录页面 URL、定义文件 URL 和具体失败请求;不要上传内部接口地址或令牌到公共测试站。

先区分原因

浏览器要分别请求 UI、OpenAPI 定义及实际 API,外部 $ref 还可能增加请求。某一处 CORS 正确不代表其余全部正确;curl 能取得响应也不能代替浏览器的跨域验收。

按顺序操作

  1. 打开浏览器 Network 与 Console,只复现一次失败。记录协议、主机和端口,确认失败的是定义文件、外部引用、预检 OPTIONS 还是实际接口。
  2. 若定义文件返回 401、404 或一张登录页面,先解决地址和访问条件;不能把所有 Failed to fetch 都叫作 CORS。
  3. 若日志明确指出跨域限制,向服务维护者提供 UI 的实际来源、失败请求的方法和请求头名称,不提供请求头里的密钥值。
  4. 维护者在相应定义文件或 API 所在层配置必要的允许来源、方法和请求头,并考虑组织现有反代规则。不要以关闭浏览器安全机制、清空认证或开放所有来源来测试。
  5. 回到原 UI 验证定义能加载,再选组织明确允许的只读接口作对照。带写入副作用的接口不要因为按钮叫 Try it out 就随手执行。
失败阶段应核对的位置
定义文件下载文档地址、返回内容及其CORS
外部 $ref 加载被引用文件自己的访问条件
OPTIONS 预检接口允许的方法、来源和头名称
实际API返回401/403认证和授权,不能由CORS替代

怎样确认有效

必须在原浏览器页面完成验证:文档结构正常、测试请求通过对应检查且返回预期只读结果。若仅用 curl 验证响应头,应明确它只能辅助看服务器响应,不能证明 UI 已可用。

无效时恢复与下一步

维护者恢复无效的临时 CORS 更改,访客保留错误证据并联系相应负责人。不要将管理接口暴露公网作为补救;内部地址需要企业网络的,继续使用原授权接入。