对着几千行的 OpenAPI 文档找一个接口时，浏览器里来回滚动、编辑器里全文搜索，都不如直接在终端里翻来得顺手。oq 就是为这个场景准备的 OpenAPI查看开源工具：它在终端里打开 OpenAPI 规范文件，让你按请求、组件和 Webhooks 分视图浏览，还能增量搜索、展开详情，不用离开命令行就能把接口定义核对清楚。
一句话定位：终端里的 OpenAPI查看器
oq 是一个用 Go 编写的终端 OpenAPI 规范查看器，支持 OpenAPI 3.0、3.1 和 3.2 的 JSON 与 YAML 文档。它用 libopenapi 解析规范文件，在终端中提供可折叠的详情、多视图导航和增量搜索，定位是查看与核对，而不是编辑规范、生成代码或执行接口调用。
| 项目 | 内容 |
|---|---|
| 软件名称 | oq |
| 软件类型 | OpenAPI查看开源工具 |
| 核心用途 | 在终端查看、搜索、核对 OpenAPI 3.x 规范 |
| 实现语言 | Go，依赖 libopenapi 解析文档 |
| 规范版本 | OpenAPI 3.0、3.1、3.2 |
| 文件格式 | JSON、YAML |
| 安装渠道 | Go 工具链、Homebrew、Arch Linux AUR、预编译二进制 |
| 许可证 | MIT 许可证 |
| 适合场景 | 接口评审、联调前核对、规范走查、开发中快速查接口 |
安装渠道怎么选
原稿明确列出的安装路径有四条，功能上没有区别，选法只看你的系统和习惯。Go 用户直接用 Go 工具链最顺手，macOS 用户走 Homebrew，Arch 用户走 AUR，不想装工具链的就拿预编译二进制文件。
| 渠道 | 适合谁 | 注意点 |
|---|---|---|
| Go 工具链安装 | 已有 Go 环境的开发者 | 装完确认 oq 命令在 PATH 里 |
| Homebrew 安装 | macOS 用户 | 与 Go 安装二选一，不要重复装两份 |
| Arch Linux AUR | Arch Linux 用户 | 按 AUR 常规流程安装即可 |
| 预编译二进制 | 不想装工具链、只想快速试用的用户 | 到 Releases 页面取对应平台的文件，运行前核对平台架构 |
安装与第一次 OpenAPI查看
第一次使用建议拿一份你熟悉的规范文件练手，先把视图和搜索的路子摸熟，再用到真实评审里。
- 按上表选一种渠道安装，装完确认 oq 命令可用。
- 准备一份 OpenAPI 3.0、3.1 或 3.2 的 JSON 或 YAML 文件，确认文件本身能被正常解析。
- 在终端用 oq 打开这份规范文件，进入查看界面。
- 先在 Requests 视图里找到一个你熟悉的接口，展开详情，核对参数、请求内容和响应内容是否与预期一致。
- 再用增量搜索搜一个组件名或字段名，验证搜索范围覆盖名称、类型、描述和详情，确认找得到你要的东西。
OpenAPI查看：三个视图怎么用
oq 把规范拆成三个视图，查接口时按视图走比全文翻找快得多。Requests 视图看接口本身，Components 视图看可复用的模型与参数定义，Webhooks 视图看回调定义。每个视图里的条目都可以展开或折叠详情，展开后能看到继承参数、必填项、类型、格式、请求与响应内容、响应头、标签和弃用信息，评审时最常核对的就是这几项。
搜索是大小写不敏感的字面量增量搜索，边输边出结果，覆盖名称、类型、描述和详情。长文档的浏览靠键盘、鼠标滚轮、分页滚动和右侧比例滚动条配合，翻到哪里、还剩多长，滚动条上一眼就能判断。建议养成固定顺序：先搜接口名定位，再展开看参数与响应，最后到 Components 里核对引用的模型定义，这样一轮走查下来很少漏项。
使用前必改的 5 处设置
oq 没有复杂的配置文件要改，但下面 5 处使用习惯必须在第一次评审前定下来，否则查得快、错得也快。
- 规范版本先确认：打开文件前先确认它是 3.0、3.1 还是 3.2，超出这三个版本的文件不要默认能正常解析，先看仓库文档或源码说明。
- 文件来源要干净：只用团队仓库或接口方正式给出的规范文件核对，评审结论以这份文件为准，不要拿来路不明的旧文件当依据。
- 弃用标记必看：展开详情时把弃用信息当作必查项，标了弃用的接口和字段要在评审结论里单独注明，避免联调时才发现用了已弃用的定义。
- 必填与类型逐项对：参数的必填项、类型和格式是联调最容易翻车的地方，展开后逐项核对，不要只看接口名和描述就放行。
- 敏感内容不上屏分享：规范文件里可能带有内部接口名和示例数据，截图或投屏分享前先检查，避免把不该公开的内容带出评审范围。
适用人群与同类方式对比
oq 最适合三类人：每天和接口打交道的后端与前端开发者、负责接口评审的 API 设计人员、需要在联调前快速核对规范的接口维护人员。如果你平时就在浏览器文档里查接口，且已经用顺手了，不必为了换工具而换工具。
| 方式 | 优点 | 短板 |
|---|---|---|
| oq 终端查看 | 不离命令行，搜索与多视图定位快 | 只做查看，原稿未说明编辑、生成、校验与请求调试能力 |
| 浏览器文档页面 | 可视化好，适合给非开发角色演示 | 大文档翻找慢，离不开浏览器 |
| 编辑器直接读文件 | 零成本，随时能改 | 没有视图拆分和结构化详情，找引用关系费劲 |
注意事项
- 原稿只明确支持 OpenAPI 3.0、3.1 和 3.2，其他规范版本的兼容性要先查看仓库文档或源码确认。
- 它是终端查看器，原稿没有说明规范编辑、代码生成、校验、请求调试或文档导出能力，需要这些能力时要另配工具，不要默认它全包。
- 原稿没有给出 Windows 安装方式或兼容性说明，Windows 用户使用前要结合源码或发布文件确认。
- 复杂规范错误、超大文档和特殊扩展字段的处理边界在公开信息里没有说明，正式评审前先用目标文件实测一遍解析效果。
- 升级或改动界面后，原稿建议运行 go test 验证，贡献解析相关代码时要覆盖三个规范版本的示例，照着仓库流程走更稳妥。
什么时候不选 oq
取舍同样要说清楚：如果你要的是改规范、生成客户端代码、跑接口测试或把文档发布成网站，oq 不对症，选它只会多绕一层。反过来，只要你的需求是在终端里把一份 OpenAPI 规范快速看明白、核对准，它就是很轻的一块拼图。先拿一份真实规范文件走一遍定位、搜索、展开详情的完整流程，顺手了再把它固定进日常评审环节。
回复【oq】获取下载方式
关注「软件教程管家」
回复软件名即取即下：网盘下载链接 + 提取码，一步直达，不用再跳转。
本站资源仅供个人学习交流，请勿用于商业用途。软件与资料版权归原作者所有；如有侵权，请通过公众号「软件教程管家」联系我们，我们将在 24 小时内下架处理。查看免责声明 ›
