访问并更新已导入 API 的文档

导入一份规范时，Restorm 不只创建请求：它还保留 API 的文档 —— 描述、模型、 安全方案、示例、枚举 —— 并把它附加到导入所创建的 环境文件夹上。

访问文档

环境文件夹的 文档 标签页

这是主要视图。打开导入生成的环境文件夹：它的子标签页栏中有一个 文档 标签页， 与 环境、自定义变量 和 笔记 并列。

该标签页只在文件夹来自一次导入时才出现 —— 您手工创建的环境文件夹没有可显示的 文档。

其他入口

入口	您会看到什么
某个请求的 文档 标签页	仅该操作的文档 —— 没有目录，也没有总体信息块。只有在规范中能找到该操作时才会出现
某个普通文件夹的 文档 标签页	仅限该文件夹所包含操作的文档
环境文件夹的首页子标签页	查看文档 卡片 —— “浏览 API 文档、模型和端点”
欢迎界面（API 卡片）	快捷链接 文档
标题栏的搜索引擎	鼠标悬停在某个结果上时显示文档预览

该视图包含什么

自上而下：

• API 标题及其描述；
• 一个信息块：Version、Source format（带指向源 URL 的链接）、Server （协议、主机、基础路径）、Contact、License、Terms of service、 External docs；
• 每个标签一个小节，并带上该标签的描述；
• 每个操作一个区块：请求方法与 URL、摘要、分组徽章、必要时显示的 deprecated 徽章、Security 小节（方案类型、OAuth 2 流程、作用域），以及一段 可折叠的 Example payload；
• Parameters 与 Responses 表格（状态码带颜色）；
• Models —— 模式的交互式图谱，可浏览、可缩放；
• Polymorphism —— oneOf / anyOf / allOf 组合；
• Enums —— 枚举，与文件夹中的枚举合并。

Note

这些小节的标题（Models、Enums、Parameters、Responses、Security、 Example payload）在应用的所有语言中都显示为英文。这里原样保留，方便您在界面上 对应查找。

从文档创建请求

每个操作区块都带有一个 + Add 按钮，可为该操作创建一个预先配置好的请求。当一次 导入不完整，或某个操作刚刚出现在规范中时，这是最短的路径。

浏览与搜索

右侧固定着一个目录 —— 小节包括 Overview、Operations、Models、Enums —— 可折叠、可调整宽度。点击某个模型会滚动到图谱处，并把对应节点居中。

快捷键	效果
Ctrl+F / Cmd+F	在文档中打开搜索
F3 / Enter	下一个匹配项
Shift+F3 / Shift+Enter	上一个匹配项
Esc	关闭搜索

一个计数器指示当前处在结果中的位置。

更新文档

规范会演进。Restorm 能重新获取源并应用差异 —— 文档和请求都一样 —— 而不会覆盖 您的工作成果。

仅适用于通过 URL 的导入

只有当文件夹是从一个 URL 导入时才能重新同步。从文件导入或粘贴导入不会记录源， 刷新按钮也不会出现：此时首页子标签页会显示 “此文件夹并非从可导入的源创建。”

该 URL 事后无法在界面中修改。要更换源，请重新做一次导入。

按钮在哪里

两个等价的入口：

1. 环境文件夹的首页子标签页，API 规范更新 小节 —— 它显示 URL、 上次导入 和 上次检查，并带有刷新按钮；
2. 在侧边栏树中右键点击该文件夹 → 刷新。

没有自动检查

Restorm 不会在后台监视您的规范，也不会提醒您有新版本可用。检查始终由您主动触发。

会发生什么

1. 获取过程中会出现一个 “正在刷新 API 规范……” 窗口。URL 和请求头中的 {{variables}} 会被解析，并且会先执行所附加的身份验证路由。
2. Restorm 会把所获取源的指纹与上次导入时记录的指纹进行比较。
3. 没有任何变化 → “API 规范已是最新。”，到此结束。
4. 有变化（或获取失败）→ 打开重新同步向导。

向导

• 源 URL 以只读方式显示。
• 一个胶囊控件可用于附加、修改或分离身份验证路由，另有一个 Custom headers 子菜单可添加每次刷新都会重放的固定请求头。
• 两个预览标签页：
  • Routes —— 新版本中找到的操作树，可筛选、可选择。您文件夹中已存在的操作 会被锁定并始终保持勾选；您只需选择要添加哪些新操作；
  • Documentation —— 新版本的文档，只读，供确认之前查看。
• 确认按钮会显示所选新操作的数量，例如 Apply update (3)。

Note

目前无论应用使用哪种语言，该向导都以英文显示（“Refresh from source”、 “Apply update”，以及 “Routes” 和 “Documentation” 标签页）。因此这里原样保留了英文 标题。

什么会被修改，什么不会

这是关键所在：规范对它所描述的内容有决定权，您对其余部分有决定权。

元素	行为
请求名称	绝不修改
请求方法与 URL	绝不修改
已有的参数、请求头和路径参数	原样保留 —— 取值、描述、启用状态
规范新增的参数	添加，取规范的默认值或留空
规范中移除的参数	保留在请求上
新操作	添加到一次全新导入会放置的位置（包括标签文件夹）
被规范标记为已弃用的操作	予以标示；在树中显示为灰显
从规范中消失的操作	标示为已移除；在树中显示为删除线，仍可执行，且绝不会被删除
API 文档与枚举	由新版本整体替换 —— 这正是刷新文档标签页的方式

您的树中永远不会有内容被删除：从源中消失的操作只会被标示，而不会被抹掉。

如果源需要身份验证

401 或 403 响应会打开向导，并原样显示错误消息（例如 HTTP 401: Unauthorized）。 附加一条身份验证路由或添加固定请求头， 预览就会重新执行。

可重新同步的格式

有十二种格式支持重新同步：Swagger 2.0、OpenAPI 3.x、GraphQL、gRPC、SOAP（WSDL）、 OData、AsyncAPI、Postman、Insomnia、Bruno、OpenRPC 和 Smithy。

对于其他所有格式，一次新的导入会创建一棵新的树。完整清单见 从源更新。