APIドキュメントを生成するツールを選ぶ際、ライセンスはその決定の一部となります。オープンソースのジェネレーターは、コードを読み、出力をセルフホストし、開発が停滞した場合にフォークでき、すでにリリースした機能でシート制限やペイウォールに遭遇することはありません。すべてのCIビルドで実行されるタスクにとって、それは出力品質と同じくらい重要です。
このリストは、コマンドラインから実行できるAPIドキュメントツールの中から、オープンソースのものを選りすぐったものです。ここに掲載されているすべてのツールは、MITまたはApache 2.0といった実際のライセンスのもとでソースコードが公開されており、GitHubでホストされ、アカウント登録なしで無料で実行できます。OpenAPIまたはSwaggerファイルを指定すると、Markdown、静的HTMLページ、または自身で所有・ホストする完全なドキュメントサイトが生成されます。
各ツールの正確なライセンスとセルフホストの状況については明記します。それが、一般的なツールではなくオープンソースのまとめを読んでいる理由のすべてだからです。より広範な分野を知りたい場合は、「REST APIドキュメントツールのトップ10」のまとめでGUIプラットフォームもカバーされています。以下に示すすべてのツールが読み込む形式は「OpenAPI Specification」ですので、有効な仕様ファイルがあなたの出発点となります。
まず正直なところを述べます。Apidogは最後の方に登場しますが、これはオープンソースのエントリーではありません。商用のフリーミアムプラットフォームです。オープンソースツールでは埋められないギャップがある場合に備えて、注釈付きで含めました。その線引きについては明確にします。
CLIドキュメントツールが「オープンソース」であるとは？
オープンソースとは単に「無料でダウンロードできる」という意味だけではありません。ビルドに組み込むドキュメントツールにとって、そのツールが真にあなたのものとなるかどうかは3つの要素で決まります。
実際のライセンス。 MITまたはApache 2.0は、そのツールを商用目的で許諾なしに利用、改変、再配布できることを意味します。どちらもOSI承認済みです。Apache 2.0には明示的な特許許諾が含まれており、一部の法務チームがこれを好みます。以下のすべてのツールは、このどちらかのライセンスを持っています。
セルフホスト可能な出力。 オープンドキュメントの要点は、何もベンダーのサーバーに依存しないことです。これらのツールは静的ファイルを出力します。コミットするMarkdown、単一のHTMLページ、またはHTML/CSS/JSのフォルダーなどです。これをGitHub Pages、S3、または通常のNginxサーバーでホストすれば、ツールの背後にあるプロジェクトがどうなろうと動作し続けます。
メンテナンスとコミュニティ。 ソースコードが利用可能であることは、そのコードが生きている場合にのみ役立ちます。スターの数、最近のコミット、未解決の問題は、もし必要になった場合にフォークが現実的であるかどうかを示します。ここにあるいくつかのツールはアーカイブされていますが、まだ動作します。それについては言及します。
オープンソースとフリーミアムの両方のオプションでコストがかからないという点については、「無料APIドキュメントツール」のリストが補完的な情報となります。それではツールを見ていきましょう。
Redocly CLI
Redocly CLIは、仕様を洗練された自己完結型HTMLリファレンスに変換する最も速い方法です。MITライセンスのオープンコアで、CLIとその基盤となるRedocレンダリングエンジンはGitHub上でオープンソースとして公開されていますが、一部のホスト型ポータル機能はRedoclyの有料製品に含まれています。`build-docs`コマンドは完全にオープンな部分に属しています。
npx @redocly/cli build-docs openapi.yaml -o api-docs.html
これにより、Redoc上に構築されたHTMLファイルが1つ作成されます。ローカルで開くか、任意の静的ホストにアップロードするか、リリースに添付することができます。外部との通信は一切なく、パッケージがキャッシュされればオフラインで実行できます。
最適な用途：1つのコマンドで作成できる、MITライセンスのセルフホスト可能なクリーンなシングルページAPIリファレンス。正直な制限：出力は1ページのみであるため、マルチページポータルというよりはリファレンスであり、より豊富なテーマ設定は有料ティアに属します。レンダリングエンジンを比較検討している場合、「Redoclyの代替ツール」の比較記事では、オープンソースの範囲がどこにあるかが説明されています。
Widdershins
WiddershinsはMITライセンスの純粋なコンバーターです。OpenAPI 3、Swagger 2、またはAsyncAPIを読み込み、Markdownを出力します。それがその唯一の仕事です。出力はプレーンなMarkdownであるため、完全にあなたのものとなります。コミットしたり、プルリクエストで差分を確認したり、すでに運用している静的サイトに組み込んだりできます。
npm install -g widdershins
widdershins openapi.yaml -o api-docs.md
Widdershinsが作成するMarkdownはSlate互換であるため、このリストの後半に登場するサイトジェネレーターと相性が良いです。便利なフラグ：`--omitHeader`はフロントマターを省略し、`--language_tabs`はコードサンプル言語を選択します。
最適な用途：仕様の内容をバージョン管理可能なMarkdownに変換し、ロックインをゼロにすること。正直な制限：得られるのはMarkdownのみです。スタイル設定やレンダリングされたサイトはないため、Widdershinsはパイプラインの片方であり、Markdownをページに変換するには別のツールが必要です。
OpenAPI Generator
OpenAPI GeneratorはApache 2.0ライセンスでコミュニティによって運営されており、2018年にSwagger Codegenからフォークされました。クライアントSDKで最もよく知られていますが、ドキュメントジェネレーターも付属しています。`markdown`ジェネレーターはMarkdownのフォルダーを出力し、`html2`は単一の自己完結型HTMLページを出力します。
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/
Apache 2.0ライセンスとその特許許諾は、慎重な法務チームにとって承認を得やすいものであり、このプロジェクトはこの分野で最も活発にメンテナンスされているものの1つです。
最適な用途：強力なコミュニティの支援と寛容なライセンスのもと、SDKとドキュメントの両方に1つのツールを再利用すること。正直な制限：npmラッパーは初回実行時にJavaのjarファイルをダウンロードするため、単一のバイナリではなく、テンプレート化された出力はシンプルです。ドキュメントのみが必要な場合は、より軽量なコンバーターが存在します。
Swagger Codegen
Swagger Codegenは、Swaggerチームが開発したオリジナルのテンプレート駆動型ジェネレーターで、Apache 2.0ライセンスです。OpenAPI Generatorのフォークよりも前から存在し、SmartBearによって現在もメンテナンスされています。ドキュメント生成には2つの方法があります。静的なシングルページリファレンス用の`html`と、小規模なインタラクティブサイト用の`dynamic-html`です。
npm install -g swagger-codegen-cli
swagger-codegen-cli generate -i openapi.yaml -l html -o docs/
これら2つのプロジェクトはDNAと多くのオプションを共有しているため、チームがすでにSwaggerツールチェーンに標準化している場合、これを使用することでそのエコシステム内に留まることができます。
最適な用途：既にSwaggerエコシステムに投資しており、スタブを生成するのと同じApache 2.0ツールでドキュメントも生成したいチーム。正直な制限：OpenAPI Generatorと同様にJavaベースであり、コミュニティフォークよりも開発の動きが遅いです。ほとんどの新規セットアップではOpenAPI Generatorの方が活発な選択肢ですが、Swagger Codegenは継続性で優位に立ちます。
DocusaurusとOpenAPIプラグイン
単一のHTMLページでは不十分で、本格的なバージョン管理されたドキュメントサイトが必要な場合、Docusaurusがオープンソースの中核となるでしょう。MITライセンスでMetaによって開発され、ウェブ上で最も広く使用されている静的サイトジェネレーターの1つです。単体ではMarkdownとMDXをレンダリングし、同じくMITライセンスでPalo Alto Networksがメンテナンスしているdocusaurus-openapi-docsプラグインを追加することで、仕様からドキュメントを生成する機能が加わります。
npx create-docusaurus@latest my-docs classic
npm install docusaurus-plugin-openapi-docs docusaurus-theme-openapi-docs
npm run docusaurus gen-api-docs all
プラグインを仕様パスで設定すると、`gen-api-docs`はOpenAPIファイルをMDXページに変換し、Docusaurusサイト内で「試す」パネルとサイドバーナビゲーション付きでレンダリングします。
最適な用途：バージョン管理、検索、手書きのガイドと生成されたリファレンスが共存する、完全なセルフホスト型ドキュメントポータル。正直な制限：ここに挙げられた中で最も重いセットアップです。Reactサイトとビルドステップを立ち上げるため、必要なのがリファレンスページだけであれば過剰です。その場合は、Redocly CLIの方が手軽な選択肢です。
Slate
Slateは、クラシックな3カラムAPIドキュメントレイアウト（左にナビゲーション、中央に説明文、右にコードサンプル）を静的サイトとしてレンダリングするツールです。Apache 2.0ライセンスでMiddlemanを基盤としているため、Rubyツールチェーンが必要です。上記のコンバーターとは異なり、SlateはOpenAPIを直接読み込まず、あなたが記述したMarkdownをレンダリングします。
# Slateフォークをクローンし、bundle installを実行した後
bundle exec middleman build
これにより、完全な静的サイトが`build/`フォルダーに書き込まれ、どこでもホストできます。ここでWiddershinsが役立ちます。仕様をMarkdownに変換し、Slateでそのおなじみのレイアウトにレンダリングするのです。
最適な用途：構造と記述に編集上のコントロールが必要な、手作業でキュレートされた物語調のドキュメントを、完全にセルフホストされた静的サイトで作成すること。正直な制限：オリジナルのリポジトリはアーカイブされていますが（メンテナーが引退したため）、ビルドは可能でフォークは活発です。また、Rubyの依存関係は`npx`のワンライナーよりも重いです。ドキュメントが仕様から直接再生成されるのであれば、コンバーターの方が軽量です。
Apidog CLI（正直な補足、オープンソースではありません）
上記のツールはすべてオープンソースであり、それぞれが「変換」「レンダリング」「静的ファイルのホスティング」のいずれかの役割を担っています。これらのツールが残すギャップは「ライブプロジェクト」です。もしあなたのAPIが単一のYAMLファイルではなく、エンドポイント、スキーマ、例を持つメンテナンスされたプロジェクトである場合、コンバーター、レンダラー、ホストを手動で連結し、これらすべてを同期させることになります。
そのギャップを埋めるのが`apidog-cli`バイナリです。ライセンスについて正直に言えば、Apidogはオープンソースではありません。無料プランのある商用フリーミアムプラットフォームであり、CLIはローカルの仕様ではなくホストされたプロジェクトと通信します。比較がオープンツールがカバーするものとそうでないものについて正直であるためだけにここに含めており、オープンソースの選択肢としてではありません。
npm install -g apidog-cli
apidog login --with-token <YOUR_TOKEN>
apidog export --project <projectId> --format markdown --output ./api-docs.md
apidog export --project <projectId> --format html --output ./api-docs.html
1度のエクスポートでプロジェクトをビルドパイプラインなしでMarkdownまたはHTMLに変換でき、`apidog doc`と`apidog docs-site`はスクリプトからドキュメントリソースを管理します。出力は構造化されたJSONなので、CIやエージェントにきれいにパイプできます。「Apidog CLI完全ガイド」では認証と各コマンドグループについて説明しています。Markdownエクスポートのワークフローを探している場合は、「Markdownエクスポート対応APIドキュメントジェネレーター」の記事でさらに詳しく解説しています。
線引きは次のとおりです。オープンツールは、あなたが所有するコード、セルフホストするファイル、ベンダーへの依存なしを提供します。Apidogは、メンテナンスされたプロジェクトから共有可能なドキュメントへの統合されたルートを提供しますが、これはホストされたフリーミアム製品であるという代償を伴います。あなたの情報源が静的な仕様なのか、それともライブプロジェクトなのかに基づいて選択してください。
選び方
あなたのチームが何を所有する必要があるかに合わせて、ライセンスと出力を選択してください。
| ツール | 最適な用途 | インストール | オープンソース？ | 出力形式 |
|---|---|---|---|---|
| Redocly CLI | 洗練された単一HTMLページ | npx @redocly/cli |
はい (MIT, オープンコア) | スタンドアロンHTML |
| Widdershins | コミット可能なMarkdownへの仕様変換 | npm i -g widdershins |
はい (MIT) | Markdown |
| OpenAPI Generator | ドキュメントとSDKを1つのツールで | npm i -g @openapitools/openapi-generator-cli |
はい (Apache 2.0) | MarkdownまたはHTML |
| Swagger Codegen | Swagger標準化チーム | npm i -g swagger-codegen-cli |
はい (Apache 2.0) | HTML |
| Docusaurus + OpenAPI plugin | 完全なセルフホスト型ドキュメントサイト | npx create-docusaurus |
はい (MIT) | 静的サイト |
| Slate | 手作業でキュレートされた3カラムのドキュメント | Ruby + Bundler | はい (Apache 2.0) | 静的サイト |
| Apidog CLI | ライブプロジェクトからのエクスポート | npm i -g apidog-cli |
いいえ (フリーミアム) | MarkdownまたはHTML |
要するに、裸の仕様と共有可能なHTMLリファレンスにはRedocly CLIを、バージョン管理したいMarkdownにはWiddershinsを使用してください。すでにSDKを生成しているのであればOpenAPI Generatorもドキュメントを生成できますし、Swaggerに標準化している場合はSwagger Codegenが役立ちます。バージョン管理とガイドを備えた本格的なポータルが必要な場合は、DocusaurusとOpenAPIプラグインがオープンソースの中核となり、手書きで編集上のコントロールが必要なドキュメントにはSlateが適しています。これらすべてのツールはソースが利用可能でセルフホスト可能なので、あなたがリリースするものがベンダーの存続に依存することはありません。より広範な無料オプションについては、「無料APIドキュメントツール」のまとめでオープンソースとフリーミアムの選択肢が網羅されています。
まとめ
オープンソースのドキュメンテーションCLIを選ぶことは、ライセンス、出力、そしてドキュメントがどこに存在するかに帰結します。MITとApache 2.0のどちらも、シート費用なしで利用、改変、セルフホストを許可するため、必要な出力を生成する最小限のツールを選びましょう。単一ページにはRedocly CLI、MarkdownにはWiddershins、SDKと並行してドキュメントを生成するならOpenAPI GeneratorまたはSwagger Codegen、ポータルにはDocusaurus、手作業でキュレートされたページにはSlateです。
もしあなたのAPIが単独のファイルではなく、メンテナンスされたプロジェクト内に存在し、3つのツールを連結するよりもドキュメントをエクスポートしたいのであれば、Apidogをダウンロードしてプロジェクトに対して`apidog export`を試してみてください。CIジョブに組み込むことでAPIが変更されるたびにドキュメントが再構築されますが、これがオープンソースのバイナリではなくフリーミアムプラットフォームであることを明確に理解しておいてください。