oq - ターミナルで使う OpenAPI Spec ビューア

Tool
oq - ターミナルで使う OpenAPI Spec ビューア

oq - ターミナルで使う OpenAPI Spec ビューア

OpenAPI（OAS）仕様書をターミナル上で対話的に閲覧できる軽量なCLIツール。Go製で単一バイナリとして動作し、YAML/JSONのOpenAPIドキュメントを標準入力やファイルから読み込み、エンドポイントやコンポーネントを折りたたんで見やすく表示します。キーボード操作で高速にナビゲートでき、API仕様の確認やレビューに適したツールです（300字程度）。

https://github.com/plutov/oq

概要

oq はターミナルベースの OpenAPI Spec（OAS）ビューアです。ローカルの openapi.yaml/json を直接開くか、パイプ経由で受け取った仕様書を解析して、エンドポイント（paths）やコンポーネント（schemas, responses など）をツリー表示します。折りたたみ・展開や上下移動、ビュー切替がキーボード中心に設計されており、軽量な単一バイナリでAPI仕様の確認やコードレビュー、ドキュメントの素早い参照に適しています。Goで実装され、クロスプラットフォームで動作が期待できます。

GitHub

リポジトリの統計情報

  • スター数: 126
  • フォーク数: 2
  • ウォッチャー数: 126
  • コミット数: 7
  • ファイル数: 14
  • メインの言語: Go

主な特徴

  • ターミナル上での対話的な OpenAPI ドキュメントビューア（エンドポイント / コンポーネントのツリー表示）
  • ファイル指定、パイプ入力、URL からの取得に対応（stdin からの読み込みが可能）
  • キーボード操作による折りたたみ、ビュー切替、クイックナビゲーション
  • 軽量な Go 実装で単一バイナリ、導入が容易

技術的なポイント

oq は Go 製の CLI アプリケーションとして、OpenAPI 仕様の解析とターミナル描画を分離して実装することで、シンプルかつ効率的なユーザー体験を提供します。入力は YAML/JSON の OpenAPI ドキュメントを想定しており、ファイルパスを渡すか標準入力（パイプ）で流し込むことで受け取れます。内部では仕様書をパースして、Paths（エンドポイント）とComponents（スキーマ等）といった主要セクションを木構造にマッピングし、各ノードに対して折りたたみ状態や選択状態を管理します。

ターミナル描画は、行単位のレンダリングとスクロール制御を組み合わせ、上下移動（矢印キー・k/j）やビュー切替（Tab）、折りたたみ（Enter/Space）といったキーボードショートカットで高速に操作できます。UI は余計なマウス依存を排し、キーボードだけで必要な情報に到達できる設計になっているため、レビューやCI環境での利用にも向いています。Go で書かれているため、ビルドすると単一の実行ファイルが得られ、依存関係が少なければ配布やコンテナ化も容易です。

設計上の注目点としては、仕様解析と表示ロジックの分離、最小限のメモリで大きな OpenAPI ドキュメントを扱える工夫、そしてユーザーの操作性を高めるキー割り当てのシンプルさが挙げられます。具体的には、Endpoints と Components の2つの主ビューを持ち、Tab キーで切り替えることで目的の情報に迅速にアクセスできる点、またエンドポイント詳細やコンポーネントの中身を折りたたんで階層的に閲覧できる点が実用的です。さらに、curl や cat からのパイプ入力に対応しているため、リモートの OpenAPI を直接取得して即座に確認できるワークフローが作れます。

拡張面では、より高度なフィルタリング（タグ別やメソッド別の絞り込み）や、JSON Schema のシンタックスハイライト、外部参照（$ref）の解決と展開表示といった機能が考えられます。現在のシンプルさを維持しつつ、必要に応じて視認性や解析の深度を高められる余地がある設計になっています。

プロジェクトの構成

主要なファイルとディレクトリ：

  • .gitignore: file
  • LICENSE: file
  • README.md: file
  • example-3.1.yaml: file
  • example.yaml: file

…他 9 ファイル

リポジトリは小規模で、実行ファイルに必要なソースとサンプル仕様ファイルが揃っているため、試用や改修が容易です。example-3.1.yaml や example.yaml がサンプルとして用意されており、動作確認や動作例の参照に便利です。

まとめ

ターミナル中心の軽量な OpenAPI ビューアで、素早い仕様確認に最適。

リポジトリ情報：

READMEの抜粋：

oq - a terminal-based OpenAPI Spec (OAS) viewer

oq preview

Usage

oq openapi.yaml
# or
cat openapi.yaml | oq
# or
curl https://api.example.com/openapi.json | oq

Keyboard Shortcuts

  • ↑/↓ or k/j - Navigate up/down through items
  • Tab - Switch between Endpoints and Components views
  • Enter or Space - Toggle fold/unfold for endpoint and component details
  • q or Ctrl+C - Quit the application

O…