oadig

肥大化したOpenAPI仕様から、必要な部分だけを抜き出すCLIツールを作った。

名前は “OpenAPI dig” の略。

リポジトリ: https://github.com/misebox/oadig

Rust製。ClaudeCodeで作った。AIが無かったら面倒すぎて作ってないと思う。スキーマや関連仕様がちゃんと存在しているものは、今の時代けっこう作りやすい。

作った理由

openapi.json は肥大化しやすい。

jq でフィルタしようにも、パパッとエンドポイント一覧を取得したり、対象のレスポンス構造だけを調べたい、みたいなときに困る。

OpenAPIスキーマ専用のCLIツールがあれば多少楽になるかな、と思って作った。

使い方

サブコマンドで操作する。

  • overview 概要（info + stats + operations）
  • operations エンドポイント一覧
  • schema コンポーネントスキーマの定義を表示
  • search 仕様全体からキーワード検索
  • validate OpenAPI 3.x スキーマに対する検証
  • convert Swagger 2.0 と OpenAPI 3.0 / 3.1 の変換

他にもいろいろある。

--filter で、メソッド・パス（glob）・タグ・operationId・summary・description・deprecated かどうか、で絞り込める。

$ref はデフォルトでインラインに展開する。循環参照は検出する。

入力は YAML / JSON で、ファイルでも標準入力でもいい。出力はデフォルトで整形済みのJSON。-c でコンパクト、-l で1行ずつ（line-delimited）。

汎用的なJSONのクエリは jq に任せていて、oadig 側ではやらない。oadig ... | jq ... で組み合わせる前提。

バージョンの話

OpenAPI はもともと Swagger という名前で始まっていて、途中で OpenAPI に名前が変わった。

バージョンによって構造が微妙に違うし、多くのツールやライブラリは全部のバージョンに対応していないことが多い。

そして、古い形式も結構使われている。例えば Amazon の SP-API なんかは古い形式だったりする。

うまくいっているのかは自信がないが、一応 Swagger 2.0 → OpenAPI 3.0 の変換もできるようにした。

反省

サブコマンドの整理に失敗したかなと思う。多すぎる。

インストール

brew install misebox/tap/oadig
# または
cargo install oadig

GitHub の Releases からビルド済みバイナリ（macOS arm64 / Linux x86_64 / Windows x86_64）を落としてもいい。

これも、main にpushしたら homebrew-tap のFormulaが自動更新されるようにした。こうしておくと、どこでも（ほぼmac限定にはなるけど）手軽にインストールできるので楽。