APIドキュメント作成におすすめの軽量CLIツール

OpenAPIファイルがあり、そこからドキュメントを作成したいと考えています。サービスを立ち上げたり、ポータルにサインインしたり、npmの半分を引っ張ってくるようなビルドステップを追加したりしたくないでしょう。必要なのは、仕様を読み込み、Markdownファイルまたはどこでもホストできる単一のHTMLページを生成する1つのコマンドだけです。

このリストはそのためのものです。ここにある各ツールは小さく、単一のバイナリ、npxのワンライナー、または一度インストールしたら忘れてしまうようなパッケージです。これらは高速に起動し、設定がほとんど不要で、フルプラットフォームを引きずることなくドキュメント作成の仕事をこなします。既存のドキュメントサイトにドロップできるMarkdownを出力するものもあれば、単独のHTMLファイルを出力するものもあります。これらすべてがCIとターミナルで動作するというのがポイントです。

より広範なドキュメンテーションプラットフォームに関心があるなら、「上位のREST APIドキュメンテーションツール」のまとめがGUIを重視した側をカバーしています。この記事は、ターミナルファーストでフットプリントの小さいものに焦点を当てています。ドキュメンテーションジェネレーターが何を読み取るかに関する公式リファレンスとしては、「OpenAPI Specification」が、以下のすべてのツールが解析する信頼できる情報源です。

APIドキュメントにおけるCLIツールの「軽量性」とは何か

軽量であることは、能力が低いということではありません。フットプリントと摩擦に関するものです。それを決定する4つの要素があります。

インストールサイズと依存関係。単一のバイナリまたは1つのnpmパッケージがフレームワークに勝ります。ドキュメントページを生成するために言語ランタイム、バンドラー、プラグインシステムをインストールする必要がある場合、出力がどうであれ、それは軽量ではありません。

起動と設定。これらの優れた点は、設定なしで仕様を読み込み、出力を生成することです。コマンドをopenapi.yamlに向け、ファイルを取得します。実行前に設定ファイルが必要なものは、ここで点数を失います。

単一目的の出力。以下の各ツールは、仕様を入力し、ドキュメントを出力するという1つのことだけを行います。MarkdownまたはHTMLで、それ以外の余計なものはありません。これが、パイプラインで高速かつ予測可能に保つ秘訣です。

どこでも実行可能。GUIなし、オープンツールへのログインなし、サーバーを稼働させ続ける必要もありません。ラップトップで動作し、CIジョブでも同じように動作します。より幅広い無料オプションについては、「無料のAPIドキュメンテーションツール」のリストにプラットフォームがありますが、これはそのCLI部分です。

さて、ツールについて、最も小さいものから順に紹介します。

Widdershins

Widdershinsは、これ以上ないほど小さいツールです。OpenAPI 3、Swagger 2、またはAsyncAPIファイルをMarkdownに変換する単一のnpmパッケージです。それがその唯一の仕事です。サイトをレンダリングしたり、サーバーを実行したりすることはありません。.mdファイルを渡して、すぐに役目を終えます。

npm install -g widdershins
widdershins openapi.yaml -o api-docs.md

生成されるMarkdownはSlate互換であり、後で静的サイトに供給する予定がある場合には重要です。便利なフラグとしては、--omitHeaderでYAMLフロントマターを削除し、--language_tabsで表示されるコードサンプル言語を制御できます。

最適な用途: コミット、差分比較、そしてあらゆるドキュメントシステムにドロップできるMarkdown形式で仕様コンテンツを取得すること。正直な限界: 得られるのはMarkdownだけです。スタイル設定も、インタラクティブな「試す」パネルも、ホストされた出力もありません。Widdershinsはコンバーターであり、レンダラーではないため、Markdownをサイトに変換する何かと組み合わせて使用します。

OpenAPI Generator (ドキュメントジェネレーター)

OpenAPI GeneratorはクライアントSDKで最もよく知られていますが、ドキュメントジェネレーターも付属しており、仕様しかない場合に便利です。markdownジェネレーターはMarkdownのフォルダを作成し、html2ジェネレーターは単一の自己完結型HTMLページを作成します。Javaを自分でインストールすることなく、npmラッパーを介して実行できます。

npm install -g @openapitools/openapi-generator-cli
openapi-generator-cli generate -g markdown -i openapi.yaml -o docs/
openapi-generator-cli generate -g html2 -i openapi.yaml -o docs-html/

npmラッパーは内部でJDKをバックエンドとするjarをダウンロードするため、初回実行時はWiddershinsよりも重くなります。その後は、1つのコマンドで生成できます。

最適な用途: SDKのために既に実行しているツールを再利用してドキュメントも出力し、MarkdownとスタンドアロンHTMLの選択肢があること。正直な限界: 出力はプレーンでテンプレート駆動であり、初回呼び出し時にjarをダウンロードするため、真の単一バイナリではありません。ドキュメントのみが必要で他に何も必要ない場合は、より軽量なオプションがあります。

Redocly CLI (build-docs)

単一のコマンドで、見栄えの良いスタンドアロンのHTMLページが必要な場合は、Redocly CLIが最短経路です。build-docsコマンドは、あなたの仕様をRedocに基づいて構築された1つの自己完結型HTMLファイルにバンドルします。サーバーも、個別のホスティングビルドも不要で、開いたり、メールで送ったり、あらゆる静的ホストにドロップしたりできるファイルが得られます。

npx @redocly/cli build-docs openapi.yaml

デフォルトではredoc-static.htmlを書き込みます。--outputで名前を変更できます。

npx @redocly/cli build-docs openapi.yaml --output api.html

npxを介して実行されるため、試すためにグローバルにインストールする必要すらありません。最適な用途: 1つのコマンドから洗練された単一ページの参照ドキュメントを生成し、クリーンなデフォルトテーマと管理すべきホスティングに関する話がないこと。正直な限界: 出力は1つのHTMLファイルであるため、マルチページドキュメントポータルではなく参照ページであり、よりリッチなテーマ設定やプレビューはRedoclyの有料プランにあります。同様のレンダラーと比較検討している場合は、「Redoclyの代替」と「Scalarの代替」の比較がトレードオフを説明しています。

Slate

Slateはここで異色の存在です。仕様からドキュメントへのコンバーターではなく、手書きのAPIドキュメントのための静的サイトジェネレーターです。Markdownを記述すると、Slateは古典的な3カラムのドキュメントレイアウト（ナビゲーション、コンテンツ、コードサンプルを並べて表示）を自己完結型の静的サイトとして構築します。Middlemanによって動いているため、Rubyが必要です。

# after cloning the slate repo and installing dependencies
bundle exec middleman build

これにより、完全な静的サイトがどこでもホストできるbuild/フォルダに書き込まれます。ここでWiddershinsが役立ちます。仕様からMarkdownを生成し、それをSlateでレンダリングさせると、Slateのレイアウトで仕様に基づいたコンテンツが得られます。

最適な用途: 構造と散文に編集上のコントロールが必要な、手作業でキュレーションされた物語形式のAPIドキュメント。正直な限界: Rubyツールチェーンが必要なため、このリストの中で最も重いオプションであり、OpenAPIを単独で読み込むことはありません。Markdownを供給する必要があります。ドキュメントが仕様から直接生成され、手作業での編集がほとんどない場合は、コンバーター単独の方が軽量です。

Apidog CLI (エクスポート + ドキュメント)

上記のオープンツールはそれぞれ、変換、レンダリング、ホスティングという一つの側面をカバーしています。APIが単独のYAMLファイルではなくプロジェクト内に既に存在する場合、それらを結合するのが摩擦となります。そこにapidog-cliバイナリが適合します。これはApidogのコマンドラインコンパニオンであり、1回のエクスポートでビルドパイプラインなしにプロジェクトをMarkdownまたはHTMLに変換します。

npmからインストールし、トークンで認証します。

npm install -g apidog-cli
apidog login --with-token <YOUR_TOKEN>

次に、プロジェクトのドキュメントをMarkdownまたはHTMLに1つのコマンドでエクスポートします。

apidog export --project <projectId> --format markdown --output ./api-docs.md
apidog export --project <projectId> --format html --output ./api-docs.html

CLIはドキュメントリソースも直接管理します。apidog docはプロジェクトのMarkdownドキュメントを扱い、apidog docs-siteは公開されたドキュメントサイトを管理するため、スクリプトやCIジョブからドキュメントをリスト表示、作成、更新できます。

apidog doc list --project <projectId>
apidog docs-site list --project <projectId>

出力は構造化されたJSONであり、他のステップにパイプしたり、エージェントに渡したりするのが簡単です。完全なコマンドの表面については、「Apidog CLI 完全ガイド」で認証、プロジェクト、および各コマンドグループについて説明しています。

ここで正直な説明をします。Apidogはオープンソースではなく、単一目的のバイナリでもありません。フリーミアムプラットフォームであり、CLIはホストされたプロジェクトと通信します。また、OpenAPIをリンティングしたり、スタイルガイドを強制したりすることもありません。RedoclyやSpectralがそれを行います。CLIが提供するのは、メンテンスされたAPIプロジェクトから共有可能なMarkdownまたはHTMLへの統合された経路であり、コンバーター、レンダラー、ホストを手動で連結する手間を省きます。特にMarkdownエクスポートの経路が必要な場合は、「Markdownエクスポート付きAPIドキュメントジェネレーター」の記事でそのワークフローを詳しく説明しています。

選び方

入力の形式と必要な出力に合わせてツールを選んでください。

簡単にまとめると、素の仕様があり、コミットするMarkdownが必要ならWiddershinsを使いましょう。共有可能なHTMLページが1つ欲しいなら、redocly build-docsが最速です。手書きでドキュメントを作成し、適切なレイアウトが必要ならSlateです。そして、APIが既にプロジェクト内にあり、エクスポートとドキュメント管理を1つのCLIで行いたいならApidogです。全体的な無料オプションの概要については、「無料APIドキュメンテーションツール」のまとめが役立つでしょう。

まとめ

軽量なドキュメンテーションツールは、ある一つのルールに集約されます。それは「必要な出力を生成する最小のものを選ぶ」ということです。Widdershinsとredocly build-docsは、ほとんどの仕様からドキュメントへのケースを単一のコマンドでカバーします。OpenAPI Generatorは、すでにSDKを生成している場合に価値があります。Slateはその重いフットプリントに見合うのは、手書きでドキュメントを作成している場合に限られます。そして、APIが単なるファイルではなく実際のプロジェクト内に存在する場合、apidog-cliのエクスポートはパイプラインなしでMarkdownまたはHTMLを提供します。

もし最後のケースがあなたに当てはまるなら、Apidogをダウンロードして、プロジェクトに対してapidog exportを試してみてください。APIが変更されるたびにドキュメントが再構築されるよう、CIジョブにきれいに組み込むことができます。