攔截源頭

• 發現管道：Threads 的討論
• 攔截源頭：GitHub 專案
• 攔截原因：常常要開 API 文件確認 endpoint，但每次都要開 Swagger UI 或 Postman，很麻煩。如果能直接在 terminal 裡看 OpenAPI spec，就像看 man page 一樣方便。

技術初探

• 官方定義：oq 是一個終端機版的 OpenAPI Spec viewer，支援 OpenAPI 3.0、3.1、3.2，支援 JSON 與 YAML 格式
• 核心賣點：
  • 在 CLI 裡直接瀏覽 OpenAPI spec
  • 支援 YAML / JSON，自動格式化
  • 內建快捷鍵 (? 查看幫助)
  • 可搭配管線指令使用 (curl … | oq)
• 適用場景：
  • 快速檢視 API 文件（不用開 Swagger UI）
  • 本地或 CI/CD pipeline debug API spec
  • 終端機重度使用者

實戰使用

快速安裝

# Go 安裝
go install github.com/plutov/oq@latest

# macOS / Linux (Homebrew)
brew install plutov/tap/oq

# Arch Linux
yay -S oq-openapi-viewer-git

Hello World

# 直接開本地檔案
oq openapi.yaml

# 或搭配管線
cat openapi.yaml | oq

# 或從遠端 spec
curl https://api.example.com/openapi.json | oq

實際使用

實際應用

• 在 CLI 快速找出 /users endpoint 的定義
• 測試 API 版本升級時，直接比較舊 spec 與新 spec
• 在 CI pipeline 裡，curl 拉取 spec，馬上檢查結構是否正確

記憶碼摘要

技術：oq
分類：CLI 工具 / API 檢視器
難度：⭐⭐☆☆☆（1-5顆星）
實用度：⭐⭐⭐⭐☆（1-5顆星）
一句話：讓你在 terminal 裡直接閱讀 OpenAPI Spec，不用再切 Swagger UI
關鍵指令：oq openapi.yaml
適用情境：開發 / debug API 時需要快速檢查 spec

結語

用過 oq 之後，我覺得 API 文件閱讀這件事終於不用離開 terminal 了。特別適合我這種 CLI-first 的開發流程：寫 code → 測 API → 查文件，全部都在一個環境內完成。

這讓我意識到，其實很多開發工具可以往「小巧、即用即走」的 CLI 工具方向進化，而不是越做越重。