Theming

基于 Token 驱动的深色/浅色主题，切换时不需要刷新页面。

Token

src/styles/tokens.ts：getThemeTokens(theme) / deriveSurfaceTokens(bg, text)：一小组固定的基础 token（背景色、文字色、强调色），再加上通过把 bg 向 text 混合而派生出的表面/边框 token，从不引入新的色相。

无需刷新即可应用

src/styles/apply-theme.ts：写入最终的 CSS 自定义属性，以及 <html> 上的 data-theme 属性；切换主题只改变变量的值，不会重新渲染组件树。

Zustand store

src/state/theme-store.ts：一个 Zustand store，把当前选中的主题持久化到 localStorage，并在首次绘制之前同步应用（不会闪一下错误主题）。

Document Model

在任何内容到达组件之前，原始 OpenAPI 文档会先被规范化成一个内存中的模型（tagGroups → endpoints），用纯 TypeScript 实现，单独测试，不依赖 React。四项职责：

  • normalize.ts: 通过 @apidevtools/swagger-parser 解引用每一个 $ref，并按 tag 对端点分组，保留声明顺序。
  • cap-depth.ts: 让一份已解引用（且可能存在循环）的 schema 能安全用于 JSON.stringify，供“Copy OpenAPI”按钮使用。
  • example.ts / schema-tree.ts: 从同一份 schema 出发，构建带类型标记的示例负载和可浏览的 schema 树，不会捏造假数据。
  • filter.ts: 供侧边栏使用的客户端搜索。

每一个遍历 schema 的函数（flattenSchema、schemaToTreeNodes、extractValidationRules）都按对象身份而不是数字深度上限来追踪已访问的节点，所以一个真正递归的 DTO 只会渲染出单独一个 (circular reference) / ↩ circular 标记，而不会展开 N 次，也不会崩溃。