DEV Community

Cover image for APIドキュメント作成用無料オープンソースCLIツール
Akira
Akira

Posted on • Originally published at apidog.com

APIドキュメント作成用無料オープンソースCLIツール

APIドキュメント生成ツールを選ぶとき、ライセンスは重要な判断基準です。オープンソースのジェネレーターなら、コードを確認し、出力をセルフホストし、開発が停滞した場合はフォークできます。すでに使っている機能でシート制限やペイウォールに遭遇することもありません。すべてのCIビルドで実行する処理では、出力品質と同じくらい重要な要素です。

今すぐApidogを試す

ここでは、コマンドラインから実行できるAPIドキュメントツールのうち、オープンソースの選択肢を整理します。掲載するツールは、MIT または Apache 2.0 などの実ライセンスでソースコードが公開され、GitHubでホストされ、アカウント登録なしで実行できます。

OpenAPI または Swagger ファイルを入力として、Markdown、静的HTML、セルフホスト可能なドキュメントサイトを生成できます。

各ツールについて、ライセンスとセルフホストの可否を明記します。より広い選択肢を確認したい場合は、GUIプラットフォームも含むREST APIドキュメントツールのトップ10も参照してください。ここで扱うツールの主な入力形式はOpenAPI Specificationです。まずは有効な仕様ファイルを用意しましょう。

なお、後半で紹介するApidogはオープンソースではありません。商用フリーミアムプラットフォームとして、オープンソースツールだけでは埋めにくいワークフローを補う選択肢です。その違いは明確に区別します。

CLIドキュメントツールが「オープンソース」であるとは？

「無料でダウンロードできる」だけでは、オープンソースとは言えません。CIに組み込むドキュメントツールでは、次の3点を確認してください。

1. 実際のライセンス

MIT または Apache 2.0 なら、通常は商用利用、改変、再配布が可能です。どちらもOSI承認済みのライセンスです。

  • MIT: シンプルで利用しやすいライセンス
  • Apache 2.0: 明示的な特許許諾を含むため、法務レビューで選ばれることがある

以下のオープンソースツールは、MIT または Apache 2.0 のいずれかで公開されています。

2. 出力をセルフホストできるか

ドキュメント生成後にベンダーのサーバーへ依存しないことも重要です。ここで扱うツールは、次のような静的ファイルを出力します。

  • Git管理できるMarkdown
  • 単一HTMLファイル
  • HTML/CSS/JavaScriptからなる静的サイト

GitHub Pages、S3、Nginxなどでホストすれば、生成ツールや提供元の状況に関係なく公開を継続できます。

3. メンテナンス状況とコミュニティ

必要になったときにフォークできるかは、ソース公開だけでは判断できません。次を確認しましょう。

  • 最近のコミット
  • オープンなIssueの状況
  • コントリビューター数
  • フォークの活動状況

一部のプロジェクトはアーカイブ済みでも利用可能です。ただし、新規導入時は保守状況をCI導入前に確認してください。

オープンソースとフリーミアムを含む無料選択肢を比較したい場合は、無料APIドキュメントツールも参考になります。

Redocly CLI

Redocly CLIは、OpenAPI仕様を洗練された自己完結型HTMLリファレンスへ変換する手軽な選択肢です。

CLIと基盤となるRedocレンダリングエンジンはMITライセンスで公開されています。一方、一部のホスト型ポータル機能はRedoclyの有料製品に含まれます。build-docsはオープンなCLI機能として利用できます。

npx @redocly/cli build-docs openapi.yaml -o api-docs.html
Enter fullscreen mode Exit fullscreen mode

生成されたapi-docs.htmlは単一ファイルです。ローカルで開く、GitHub Releasesに添付する、任意の静的ホストへ配置するといった運用ができます。

CIでは、たとえば次のように生成物を固定できます。

npx @redocly/cli build-docs openapi.yaml -o public/api-docs.html
Enter fullscreen mode Exit fullscreen mode

Redocly CLIの出力例

最適な用途

  • 1コマンドで単一HTMLのAPIリファレンスを作りたい
  • MITライセンスのツールを使いたい
  • 生成結果をそのままセルフホストしたい

制限

  • 出力は基本的に単一ページ
  • 複数ページ構成のポータル用途には向かない
  • より高度なテーマ設定には有料機能が含まれる場合がある

レンダリングエンジンを比較するなら、Redoclyの代替ツールも確認してください。

Widdershins

Widdershinsは、OpenAPI 3、Swagger 2、AsyncAPIをMarkdownへ変換するMITライセンスのコンバーターです。

npm install -g widdershins
widdershins openapi.yaml -o api-docs.md
Enter fullscreen mode Exit fullscreen mode

出力はプレーンなMarkdownです。そのため、生成結果をそのままリポジトリにコミットし、プルリクエストで差分レビューできます。

git add api-docs.md
git diff --cached
Enter fullscreen mode Exit fullscreen mode

便利なオプションもあります。

# フロントマターを省略する
widdershins openapi.yaml --omitHeader -o api-docs.md

# コードサンプルの言語タブを指定する
widdershins openapi.yaml \
  --language_tabs 'javascript:JavaScript' 'python:Python' \
  -o api-docs.md
Enter fullscreen mode Exit fullscreen mode

WiddershinsのMarkdownはSlate互換なので、後述するSlateと組み合わせて静的ドキュメントサイトを作ることもできます。

Widdershinsの出力例

最適な用途

  • OpenAPI仕様をバージョン管理可能なMarkdownへ変換したい
  • 生成物の編集・差分レビューを重視したい
  • 特定のホスティングサービスに依存したくない

制限

  • 出力はMarkdownのみ
  • レンダリング済みサイトは別ツールで作る必要がある

OpenAPI Generator

OpenAPI Generatorは、コミュニティ主導で開発されているApache 2.0ライセンスのツールです。2018年にSwagger Codegenからフォークされました。

SDK生成で知られていますが、ドキュメントジェネレーターも提供しています。

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/
Enter fullscreen mode Exit fullscreen mode

SDKとドキュメントを同じOpenAPIファイルから生成したい場合に便利です。

openapi-generator-cli generate -g typescript-fetch -i openapi.yaml -o sdk/
openapi-generator-cli generate -g markdown -i openapi.yaml -o docs/
Enter fullscreen mode Exit fullscreen mode

Apache 2.0の特許許諾を重視する組織にも選択肢になります。

OpenAPI Generatorの出力例

最適な用途

  • SDKとドキュメントを1つのツールチェーンで生成したい
  • Apache 2.0ライセンスを要件にしている
  • 活発なコミュニティのあるプロジェクトを採用したい

制限

  • npmラッパーは初回実行時にJavaのjarファイルを取得する
  • 軽量な単一バイナリではない
  • ドキュメントだけが必要な場合は、WiddershinsやRedocly CLIの方がシンプルな場合がある

Swagger Codegen

Swagger Codegenは、Swaggerチームが開発したApache 2.0ライセンスのテンプレート駆動型ジェネレーターです。OpenAPI Generatorの元となったプロジェクトで、SmartBearによりメンテナンスされています。

静的なシングルページリファレンスにはhtml、小規模なインタラクティブサイトにはdynamic-htmlを使用できます。

npm install -g swagger-codegen-cli
swagger-codegen-cli generate -i openapi.yaml -l html -o docs/
Enter fullscreen mode Exit fullscreen mode

既にSwaggerツールチェーンを利用しているチームなら、同じエコシステム内でドキュメント生成を完結できます。

Swagger Codegenの出力例

最適な用途

  • Swaggerエコシステムに標準化済み
  • スタブ・SDK生成と同じ系統のツールを使いたい
  • Apache 2.0ライセンスを採用したい

制限

  • Javaベース
  • OpenAPI Generatorより開発速度が緩やかな場合がある
  • 新規導入ではOpenAPI Generatorの方が活発な選択肢になることが多い

DocusaurusとOpenAPIプラグイン

単一HTMLではなく、バージョン管理・検索・ガイド記事を備えたドキュメントポータルが必要なら、Docusaurusが有力です。

DocusaurusはMetaが開発するMITライセンスの静的サイトジェネレーターです。MarkdownとMDXをレンダリングできます。docusaurus-openapi-docsプラグインを追加すると、OpenAPI仕様からAPIリファレンスページを生成できます。

npx create-docusaurus@latest my-docs classic
cd my-docs

npm install docusaurus-plugin-openapi-docs docusaurus-theme-openapi-docs
npm run docusaurus gen-api-docs all
Enter fullscreen mode Exit fullscreen mode

設定では、OpenAPIファイルのパスと出力先を指定します。たとえば、プラグイン設定に仕様を登録したうえでgen-api-docsを実行すると、MDXページとして生成されます。

npm run docusaurus gen-api-docs all
npm run build
Enter fullscreen mode Exit fullscreen mode

生成後のbuild/をGitHub PagesやS3へデプロイすれば、完全にセルフホストできます。

Docusaurus OpenAPIプラグインの出力例

最適な用途

  • バージョン管理されたドキュメントポータルを運用したい
  • 手書きガイドと生成済みAPIリファレンスを統合したい
  • 検索、ナビゲーション、複数ページ構成が必要

制限

  • Reactベースのサイト構築とビルドステップが必要
  • 単一のリファレンスページだけならセットアップが重い
  • 単純なHTML出力にはRedocly CLIの方が手軽

Slate

Slateは、左にナビゲーション、中央に説明、右にコードサンプルを配置するクラシックな3カラムAPIドキュメントを生成するツールです。

Apache 2.0ライセンスで公開されており、Middlemanを基盤としているためRuby環境が必要です。OpenAPIを直接読み込むのではなく、Markdownをレンダリングします。

# Slateフォークをクローンし、bundle installを実行した後
bundle exec middleman build
Enter fullscreen mode Exit fullscreen mode

静的サイトはbuild/ディレクトリに出力されます。

Widdershinsと組み合わせる場合は、次のような流れになります。

# OpenAPIからMarkdownを生成
widdershins openapi.yaml -o source/index.html.md

# Slateで静的サイトをビルド
bundle exec middleman build
Enter fullscreen mode Exit fullscreen mode

最適な用途

  • 3カラムのAPIドキュメントレイアウトを使いたい
  • Markdownを編集しながら説明や構成を細かく制御したい
  • 完全にセルフホストできる静的サイトが必要

制限

  • オリジナルリポジトリはアーカイブ済み
  • 実用にはフォークの活動状況を確認する必要がある
  • RubyとBundlerの依存関係が必要
  • OpenAPIから直接再生成するだけなら、他のコンバーターの方が軽量

Apidog CLI（正直な補足：オープンソースではありません）

ここまでのツールは、仕様を変換する、レンダリングする、静的ファイルをホストする、といった処理を分担します。

一方で、APIが単一のYAMLファイルではなく、エンドポイント、スキーマ、例を含む継続的に管理されたプロジェクトである場合、複数ツールの同期が必要になります。

Apidogのプロジェクト画面

apidog-cliは、このようなプロジェクトからドキュメントをエクスポートするためのCLIです。ただし、Apidogはオープンソースではありません。無料プランを持つ商用フリーミアムプラットフォームであり、CLIはローカル仕様ではなくホストされたプロジェクトと通信します。

npm install -g apidog-cli

apidog login --with-token <YOUR_TOKEN>

# Markdownとしてエクスポート
apidog export --project <projectId> --format markdown --output ./api-docs.md

# HTMLとしてエクスポート
apidog export --project <projectId> --format html --output ./api-docs.html
Enter fullscreen mode Exit fullscreen mode

apidog docとapidog docs-siteを使えば、スクリプトからドキュメントリソースを管理できます。出力は構造化JSONのため、CIや自動化処理へパイプしやすい構成です。

認証やコマンドグループの詳細はApidog CLI完全ガイドを参照してください。Markdownエクスポートの運用に焦点を当てる場合は、Markdownエクスポート対応APIドキュメントジェネレーターも役立ちます。

整理すると、次の違いがあります。

  • オープンソースツール: コードと出力を所有し、ベンダーに依存せずセルフホストできる
  • Apidog: 管理されたAPIプロジェクトから共有可能なドキュメントへエクスポートできるが、ホスト型フリーミアム製品に依存する

情報源が静的なOpenAPIファイルなのか、クラウド上で管理するライブプロジェクトなのかで選択してください。

選び方

チームが必要とするライセンス、出力形式、運用方法に合わせて選びます。

ツール 最適な用途 インストール オープンソース？ 出力形式
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

実装方針を短くまとめると、次のようになります。

  • OpenAPIから共有可能なHTMLを1つ作りたい: Redocly CLI
  • MarkdownをGitで管理したい: Widdershins
  • SDKとドキュメントを同時に生成したい: OpenAPI Generator
  • Swaggerツールチェーンを継続利用したい: Swagger Codegen
  • ガイド、検索、バージョン管理を含むポータルが必要: Docusaurus + OpenAPI plugin
  • 編集者主導の3カラムドキュメントが必要: Slate
  • 管理済みAPIプロジェクトから直接エクスポートしたい: Apidog CLI

より広範な無料ツールを比較する場合は、無料APIドキュメントツールも確認してください。

まとめ

オープンソースのドキュメンテーションCLIを選ぶポイントは、ライセンス、出力形式、ドキュメントの配置先です。

MITとApache 2.0はいずれも、利用・改変・セルフホストを可能にします。まずは必要な出力を作れる最小のツールから始めるのが実践的です。

  • 単一ページのリファレンス: Redocly CLI
  • Markdown: Widdershins
  • SDKと並行した生成: OpenAPI GeneratorまたはSwagger Codegen
  • ドキュメントポータル: Docusaurus
  • 手作業で編集するページ: Slate

APIが単独の仕様ファイルではなく、継続的に管理しているプロジェクトであり、複数ツールを連結するより直接エクスポートしたい場合は、Apidogをダウンロードしてapidog exportを試せます。CIジョブへ組み込めば、API変更時にドキュメントを再生成できます。ただし、これはオープンソースのバイナリではなく、フリーミアムプラットフォームです。

Top comments (0)