OpenAPIファイルからドキュメントを生成したい場合、サービスのセットアップ、ポータルへのサインイン、大規模なビルド環境の追加は必須ではありません。必要なのは、仕様を読み込み、Markdownまたはどこでもホストできる単一HTMLファイルを出力するコマンドです。
この記事では、ターミナルやCIで使いやすい軽量なOpenAPIドキュメント生成ツールを紹介します。単一バイナリ、npx のワンライナー、または一度インストールすれば使い続けられるパッケージに絞っています。既存のドキュメントサイトへ組み込めるMarkdownを出力するものも、単体で配布できるHTMLを生成するものもあります。
GUI中心の選択肢も含めて比較したい場合は、上位のREST APIドキュメンテーションツールも参照してください。各ツールが解析するOpenAPIの仕様については、公式のOpenAPI Specificationを確認できます。
APIドキュメントにおけるCLIツールの「軽量性」とは何か
軽量であることは、機能が少ないことではありません。重要なのは、セットアップと運用時の摩擦が少ないことです。CLIツールを選ぶときは、次の4点を確認してください。
依存関係が少ないこと
単一パッケージまたは単一コマンドで動くツールは、CIへの導入が容易です。ドキュメント生成のためだけにランタイム、バンドラー、プラグイン群を追加する必要があるなら、軽量とは言いにくいでしょう。設定なしで実行できること
理想は、openapi.yamlを渡して成果物を受け取るだけの操作です。設定ファイルやサーバー起動を必要としないツールほど、自動化しやすくなります。出力が明確であること
入力はOpenAPI仕様、出力はMarkdownまたはHTML。このように役割が限定されているツールは、パイプライン内での挙動を予測しやすくなります。ローカルとCIの両方で動くこと
GUIやログイン、常駐サーバーに依存しないことが重要です。同じコマンドを開発環境とGitHub ActionsなどのCIで実行できる構成を選びましょう。
より幅広い選択肢を確認したい場合は、無料のAPIドキュメンテーションツールも参考になります。
以下では、最小構成で始めやすい順に紹介します。
Widdershins
Widdershinsは、OpenAPI 3、Swagger 2、AsyncAPIをMarkdownへ変換するためのnpmパッケージです。HTMLのレンダリングやサーバー起動は行わず、仕様ファイルを入力して .md ファイルを出力します。
npm install -g widdershins
widdershins openapi.yaml -o api-docs.md
グローバルインストールを避けたい場合は、npx でも実行できます。
npx widdershins openapi.yaml -o api-docs.md
よく使うオプションは次のとおりです。
# YAMLフロントマターを出力しない
widdershins openapi.yaml -o api-docs.md --omitHeader
# コードサンプルの言語タブを指定する
widdershins openapi.yaml -o api-docs.md \
--language_tabs 'shell:curl' 'javascript:JavaScript'
向いているケース
- OpenAPI仕様をMarkdownとしてGit管理したい
- 生成結果を差分レビューしたい
- Docusaurus、MkDocs、Slateなど、既存のMarkdown対応サイトへ組み込みたい
注意点
Widdershinsはコンバーターです。生成されるのはMarkdownであり、スタイル付きHTMLサイトや「Try it」機能は提供しません。公開サイトが必要なら、Markdownをレンダリングする別の仕組みと組み合わせます。
CIでは、仕様変更時に生成結果が更新されているか検証できます。
widdershins openapi.yaml -o docs/api.md
git diff --exit-code docs/api.md
OpenAPI Generator（ドキュメントジェネレーター）
OpenAPI GeneratorはSDK生成で知られていますが、ドキュメント生成にも使えます。markdown ジェネレーターはMarkdownファイル群を、html2 ジェネレーターは自己完結型HTMLを生成します。
npm install -g @openapitools/openapi-generator-cli
# Markdownを生成
openapi-generator-cli generate \
-g markdown \
-i openapi.yaml \
-o docs/
# HTMLを生成
openapi-generator-cli generate \
-g html2 \
-i openapi.yaml \
-o docs-html/
SDKとドキュメントを同じ仕様から生成する場合は、スクリプトにまとめると管理しやすくなります。
openapi-generator-cli generate -g typescript-fetch -i openapi.yaml -o sdk/
openapi-generator-cli generate -g markdown -i openapi.yaml -o docs/
向いているケース
- すでにOpenAPI GeneratorでSDKを生成している
- 同じCLIでSDKとドキュメントの生成を統一したい
- MarkdownとHTMLの両方を選べるようにしたい
注意点
npmラッパーは内部でJDKをバックエンドとするjarをダウンロードします。そのため、初回実行はWiddershinsより重くなります。また、出力はテンプレートベースで、デザイン面の自由度は限定的です。
Redocly CLI（build-docs）
単一の見栄えがよいHTMLファイルを最短で作りたい場合は、Redocly CLIの build-docs が実用的です。OpenAPI仕様を入力すると、Redocベースの自己完結型HTMLを出力します。
npx @redocly/cli build-docs openapi.yaml
デフォルトでは redoc-static.html が作成されます。ファイル名を指定する場合は --output を使います。
npx @redocly/cli build-docs openapi.yaml --output api.html
生成したHTMLは、そのまま静的ホスティングへ配置できます。
npx @redocly/cli build-docs openapi.yaml --output public/api.html
向いているケース
- 単一コマンドで共有可能なAPIリファレンスを作りたい
- サーバーや追加ビルドなしでHTMLを配布したい
- Pull RequestやリリースごとにHTML成果物を生成したい
注意点
出力は単一HTMLファイルです。複数ページのドキュメントポータルを構築する用途には向きません。より高度なテーマ設定やプレビュー機能については、Redoclyのプランごとに提供範囲が異なります。
類似ツールとの違いは、Redoclyの代替やScalarの代替も参考になります。
Slate
Slateは、OpenAPI仕様を直接変換するツールではありません。手書きのMarkdownからAPIドキュメントサイトを構築する静的サイトジェネレーターです。ナビゲーション、本文、コードサンプルを並べる3カラムレイアウトが特徴です。
SlateはMiddlemanを利用するため、Ruby環境が必要です。
# Slateリポジトリをcloneし、依存関係をインストールした後
bundle exec middleman build
ビルド結果は build/ ディレクトリへ出力され、任意の静的ホスティングに配置できます。
Widdershinsと組み合わせる場合は、まず仕様からMarkdownを生成します。
widdershins openapi.yaml -o source/index.html.md
bundle exec middleman build
向いているケース
- エンドポイント一覧だけでなく、設計方針やチュートリアルも丁寧に書きたい
- 生成ドキュメントに編集上のコントロールが必要
- 定型のAPIドキュメントレイアウトを使いたい
注意点
Rubyツールチェーンが必要であり、この一覧では比較的重い選択肢です。また、Slate自体はOpenAPIを読み込みません。仕様から生成する場合は、WiddershinsなどでMarkdownを用意する必要があります。
Apidog CLI（エクスポート + ドキュメント）
Widdershins、OpenAPI Generator、Redocly CLIは、主にローカルの仕様ファイルを変換します。一方、API定義がすでにプロジェクトとして管理されている場合は、エクスポート、レンダリング、公開フローを手作業でつなぐ必要が出てきます。
apidog-cli は、ApidogプロジェクトをMarkdownまたはHTMLとしてエクスポートするコマンドラインツールです。
まずインストールし、トークンで認証します。
npm install -g apidog-cli
apidog login --with-token <YOUR_TOKEN>
続いて、プロジェクトのドキュメントをMarkdownまたはHTMLとして出力します。
# Markdownとして出力
apidog export \
--project <projectId> \
--format markdown \
--output ./api-docs.md
# HTMLとして出力
apidog export \
--project <projectId> \
--format html \
--output ./api-docs.html
プロジェクト内のMarkdownドキュメントや公開ドキュメントサイトもCLIから扱えます。
# プロジェクトのドキュメントを一覧表示
apidog doc list --project <projectId>
# ドキュメントサイトを一覧表示
apidog docs-site list --project <projectId>
出力は構造化JSONのため、CIスクリプトや後続処理へ渡しやすい形式です。認証、プロジェクト操作、コマンドグループの詳細はApidog CLI 完全ガイドを確認してください。
向いているケース
- APIが単一のYAMLファイルではなく、Apidogプロジェクトとして管理されている
- プロジェクトからMarkdownまたはHTMLを直接エクスポートしたい
- ドキュメント操作をCIやスクリプトから実行したい
注意点
Apidogはオープンソースの単一目的バイナリではなく、CLIはホストされたプロジェクトと通信します。また、OpenAPIのリンティングやスタイルガイドの強制を目的としたツールではありません。その用途にはRedoclyやSpectralを検討してください。
Markdownエクスポートのワークフローについては、Markdownエクスポート付きAPIドキュメントジェネレーターで詳しく確認できます。
選び方
入力形式と必要な出力から選ぶと迷いません。
| ツール | 最適な用途 | インストール | オープンソース？ | 出力 |
|---|---|---|---|---|
| Widdershins | SpecからMarkdownへ高速変換 | npm i -g widdershins |
はい（MIT） | Markdown |
| OpenAPI Generator | SDKと並行してドキュメント生成 | npm i -g @openapitools/openapi-generator-cli |
はい（Apache 2.0） | MarkdownまたはHTML |
| Redocly CLI | 洗練された単一HTMLページ | npx @redocly/cli |
はい（MIT、オープンコア） | スタンドアロンHTML |
| Slate | 手作業でキュレーションしたドキュメントサイト | Ruby + Bundler | はい（Apache 2.0） | 静的サイト |
| Apidog CLI | ライブプロジェクトからのエクスポート | npm i -g apidog-cli |
いいえ（フリーミアム） | MarkdownまたはHTML |
実装方針としては、次のように選べます。
- 仕様ファイルからMarkdownを生成してコミットしたい: Widdershins
-
共有しやすい単一HTMLを作りたい:
redocly build-docs - SDKとドキュメントを同じ生成基盤で管理したい: OpenAPI Generator
- 説明文やガイドを手作業で整えた静的サイトにしたい: Slate
- 既存のApidogプロジェクトからエクスポートしたい: Apidog CLI
無料で使える選択肢を広く比較したい場合は、無料APIドキュメンテーションツールも役立ちます。
まとめ
軽量なドキュメント生成では、「必要な出力を作れる最小のツールを選ぶ」ことが重要です。
- Markdownが必要ならWiddershins
- 単一HTMLが必要なら
redocly build-docs - SDK生成も行うならOpenAPI Generator
- 手書きドキュメントを構築するならSlate
- プロジェクト管理済みAPIからエクスポートするなら
apidog-cli
APIがApidogプロジェクト内で管理されている場合は、Apidogをダウンロードし、apidog export をCIへ組み込むことで、API変更に合わせてドキュメントを再生成できます。
Top comments (0)