Swagger Editor 与 UI：交互预览不是契约主源

Swagger 编辑与交互预览Editor 给即时反馈，UI 发真实浏览器请求，Git 中的 OpenAPI 才是主源。高清原图

Editor 的绿色预览只是一位消费者的判断

Swagger Editor 适合编辑 OpenAPI 并即时观察解析结果，但 Web 版输入可能进入外部服务或浏览器存储。内部契约优先使用固定镜像在本地运行，并由 Git 管理根文件。官方当前文档明确区分现行 Editor 与 Editor Next；支持哪条 OpenAPI 版本线必须随实际镜像记录。

docker run --rm -p 8080:8080 swaggerapi/swagger-editor@sha256:<digest>

镜像应使用真实 digest，示例占位不能直接执行。升级时用包含引用、鉴权、联合类型和上传下载的固定契约双跑，比较诊断与渲染，不用“能打开”作为验收。

Swagger UI 是浏览器客户端

Swagger UI 读取 OpenAPI 后渲染文档；启用 Try it out 时，它会从用户浏览器发出真实请求，因此受 CORS、Cookie、CSP、代理和证书约束。页面 401 先检查最终 server URL、预检、security scheme、OAuth client 和 scope，不把生产授权关闭。

docker run --rm -p 8081:8080 \
  -e SWAGGER_JSON=/spec/openapi.yaml \
  -v "$PWD/docs/api:/spec:ro" \
  swaggerapi/swagger-ui@sha256:<digest>

只读挂载可以防止容器改写主源。公共页面发布前检查内网 server、真实 examples、未发布路径和授权配置；关闭 Try it out 只能减少交互面，不能替代服务端权限。

配置与插件属于执行面

request interceptor、response interceptor、自定义插件和 OAuth 配置可以读取请求、token 与响应。它们按前端可执行代码评审，限制依赖、来源和日志。不要把长期 client secret 编进静态页面；适合浏览器的 OAuth 流也要使用受控 redirect URI 与最小 scope。

团队长期保留 Swagger 的版本、镜像 digest、加载的契约 artifact、公开过滤规则与回滚方式。停用时删除静态站点、镜像入口、OAuth client 和缓存制品；契约主源不随 UI 一起删除。

官方资料：Swagger Editor、Swagger UI。