APIドキュメントは、誰かが仕様を編集し、リファレンスの再生成を忘れた瞬間に古くなります。この問題を防ぐには、ドキュメント生成を手動作業ではなくビルド工程として扱います。単一コマンドで生成できれば、そのコマンドをCIに組み込み、マージやプッシュのたびに実行できます。
ターミナルベースの運用には、さらに利点があります。コマンドはスクリプト化でき、レビュー可能な差分を残せます。AIエージェントやCIランナーもブラウザを開かずに実行できるため、GUIでのクリック操作や「エクスポートを押したか」の確認は不要です。
このガイドでは、まずOpenAPIファイルを単一コマンドでスタンドアロンHTMLまたはMarkdownに変換する方法を紹介します。続いて、ライブプロジェクトからドキュメントを直接抽出し、ソースと出力を同期させられる Apidog CLIの運用を説明します。
関連情報は、トップREST APIドキュメンテーションツールと無料APIドキュメンテーションツールも参照してください。
開始に必要なのはOpenAPI 3.xファイルです。以下のコマンドの多くは、openapi.yaml と openapi.json を同様に扱えます。
Redocly CLIでHTMLリファレンスを構築する
Redocly CLIは、OpenAPI記述を自己完結型のHTMLページへ変換する方法です。Redocで仕様をレンダリングし、スタイル・スクリプト・コンテンツを1ファイルに出力します。生成物は任意の静的ホスティングに配置できます。
まず、グローバルにインストールします。
npm install @redocly/cli -g
インストールせず、npxで実行する運用も可能です。
仕様からHTMLを生成します。
redocly build-docs openapi.yaml
デフォルトでは、カレントディレクトリに redoc-static.html が生成されます。任意の出力先を指定するには、--output を使います。
redocly build-docs openapi.yaml --output docs/index.html
CIで扱う場合は、出力先を固定しておくと成果物の管理が簡単です。
mkdir -p docs
redocly build-docs openapi.yaml --output docs/index.html
このワークフローは、入力ファイル・コマンド・HTML成果物がそれぞれ1つです。Swagger 2.0およびOpenAPI 3.0/3.1の記述をレンダリングできます。
ただし、build-docs が生成するのはAPIリファレンスです。長文ガイド、チュートリアル、入門ページは別途管理してください。
WiddershinsでMarkdownを生成する
ドキュメントサイト、静的サイトジェネレーター、またはリポジトリの docs/ ディレクトリに置く用途では、Markdown出力が適しています。Widdershinsは、OpenAPI、Swagger、AsyncAPIの定義をSlate互換Markdownへ変換します。
インストールします。
npm install -g widdershins
OpenAPIファイルをMarkdownに変換します。
widdershins openapi.yaml -o api.md
-o を省略すると標準出力へ書き込まれるため、パイプ処理にも使えます。
widdershins openapi.yaml | tee docs/api.md
コードサンプルの言語タブを指定することもできます。
widdershins openapi.yaml \
--language_tabs 'shell:cURL' 'python:Python' \
-o api.md
Markdownファーストのドキュメントパイプラインでは、Widdershinsが適しています。Markdownエクスポート対応のAPIドキュメントジェネレーターのガイドも、周辺ツールの選定に役立ちます。
RedoclyとWiddershinsには共通の注意点があります。どちらもディスク上の静的ファイルを入力として読むため、openapi.yaml 自体が古ければ、生成されるドキュメントも古くなります。
Apidog CLIを使用してライブプロジェクトからドキュメントを作成する
Apidogはオープンソースではありませんが、無料枠と apidog-cli を組み合わせることで、プロジェクト内のエンドポイント、スキーマ、記述ドキュメントをまとめて管理できます。CLIはそのライブプロジェクトからオンデマンドでエクスポートします。
チームが編集するプロジェクトをエクスポート元にするため、ディスク上の仕様ファイルとの乖離を避けられます。
CLIをインストールします。
npm install -g apidog-cli
初回セットアップでは、Apidog CLIインストールガイドでNode.jsのバージョンとPATH設定を確認してください。
次に、パーソナルアクセストークンで認証します。
apidog login --with-token <TOKEN>
トークンは保存されるため、以降のコマンドで毎回渡す必要はありません。以後の操作はプロジェクトIDに対して行います。
コマンドを実行する前に、必ず --help で利用中バージョンのフラグを確認してください。
apidog export --help
仕様をプロジェクトにインポートする
APIがすでにOpenAPIファイルとして存在する場合は、まずプロジェクトへインポートします。
apidog import --help
apidog import --project <projectId> --format openapi --file ./openapi.json
apidog import はOpenAPI 3.x、Swagger 2.0、Postman、Apidog形式を受け入れます。Postmanコレクションや既存のApidogエクスポートも同様に取り込めます。
インポート後、そのプロジェクトがCLIエクスポートのライブソースになります。
人間が読めるドキュメントをエクスポートする
apidog export では、OpenAPI、HTML、Markdown、Postman形式を出力できます。利用できる形式と出力フラグはバージョンで確認してください。
apidog export --help
Markdownリファレンスを出力する例です。
apidog export \
--project <projectId> \
--format markdown \
--output ./api-docs.md
出力された api-docs.md には、プロジェクトの現在の状態から生成されたリファレンスが含まれます。
HTMLが必要な場合は、出力形式を変更します。
apidog export \
--project <projectId> \
--format html \
--output ./api-docs.html
下流ツールへ渡すポータブルな仕様が必要なら、OpenAPIとして再エクスポートできます。
apidog export \
--project <projectId> \
--format openapi \
--output ./openapi.json
プロジェクトに複数サービスがあり、一部だけを対象にしたい場合はエクスポート時にスコープを絞ります。サービスごとに1つのドキュメントファイルを生成する場合は、バージョン・ID関連のフラグを apidog export --help で確認してください。
リファレンスだけでなく、記述されたガイドも管理する
スキーマから生成するリファレンスだけでは不十分なことがあります。入門ガイド、認証のウォークスルー、移行メモなどの記述ドキュメントも必要です。
Apidogでは、これらをプロジェクトのドキュメントツリーにあるMarkdownドキュメントとして管理し、CLIの doc コマンドグループで操作します。
まず、利用可能なサブコマンドとフラグを確認します。
apidog doc --help
apidog doc list --project <projectId>
基本的な流れは次のとおりです。
- プロジェクトIDを指定してコマンドを実行する
- JSONの結果を確認する
- 返される
agentHints.nextStepsに従う
コマンドがJSONペイロードを要求する場合、CLIは期待するスキーマを出力します。送信前にローカルで検証すれば、不足フィールドをAPI呼び出し前に検出できます。正確な検証サブコマンドは次で確認してください。
apidog cli-schema --help
ドキュメントサイトを公開する
リファレンスとガイドを用意した後は、ターミナルから公開ドキュメントも管理できます。
apidog docs-site --help
apidog shared-doc --help
各コマンドの役割は次のとおりです。
| コマンド | 対象 |
|---|---|
doc |
プロジェクトのAPIツリー内にあるMarkdownドキュメント |
docs-site |
ホストされた公開ドキュメントサイト |
shared-doc |
共有可能なドキュメントリンク |
UIでクリックして作成する代わりに、公開サイトをターミナルから定義したい場合は docs-site を使います。パートナーに共有するリンクが必要なら shared-doc を使います。
公開もスクリプト化できます。仕様変更後にプロジェクトを再インポートまたは編集し、公開コマンドを再実行すれば、ホストされたドキュメントへ更新を反映できます。
CIに組み込む
CLIを使う主な理由は再現性です。ローカルで動くコマンドは、同じ条件を用意すればCIでも実行できます。
以下は、GitHub ActionsでMarkdownリファレンスを再生成する最小構成です。
- name: Regenerate API docs
run: |
npm install -g apidog-cli
apidog login --with-token ${{ secrets.APIDOG_TOKEN }}
apidog export --project ${{ secrets.APIDOG_PROJECT }} --format markdown --output ./docs/api-docs.md
生成されたファイルをコミット対象にする場合は、後続ステップで差分を検出し、必要に応じてコミット・プッシュする処理を追加します。
RedoclyまたはWiddershinsを使う場合も構造は同じです。CLIをインストールし、仕様を入力としてドキュメントを生成し、成果物を保存します。
- name: Build HTML API docs with Redocly
run: |
npm install -g @redocly/cli
redocly build-docs openapi.yaml --output docs/index.html
この形にすると、ドキュメントは「誰かが実施する作業」ではなく、毎回再生成されるビルド成果物になります。コマンド全体はApidog CLI完全ガイドで確認できます。
よくある落とし穴
間違った、または不足しているプロジェクトID
Apidogのexport、doc、docs-site呼び出しには--project <projectId>が必要です。指定するのは人間が読めるプロジェクト名ではなく、プロジェクト設定にあるIDです。プロジェクト関連のエラーが出る場合は、まずIDを確認してください。CIでトークンが設定されていない
apidog loginは、実行したマシンにトークンを保存します。新しいCIランナーには保存済みトークンがないため、エクスポート前に同じジョブでlogin --with-tokenを実行する必要があります。トークンは必ずCIのシークレットに保存し、ワークフローファイルへ直接書かないでください。古いファイルをエクスポートしている
RedoclyとWiddershinsは、渡されたファイルをそのまま読み取ります。openapi.yamlが古ければ、ドキュメントも古くなります。Apidogではライブプロジェクトからエクスポートすることで、この乖離を回避できます。--helpを読まずにフラグを推測している
export、doc、docs-site、shared-docのフラグはCLIのバージョンによって異なる場合があります。次の形式で確認してから実装してください。
apidog <command> --help
数秒の確認で、CI上の失敗したビルドを避けられます。
まとめ
ターミナルからAPIドキュメントを生成する際は、必要な出力形式とソースの置き場所で選択します。
- スタンドアロンHTMLリファレンスが必要なら Redocly CLI
- ドキュメントサイト向けのMarkdownが必要なら Widdershins
- リファレンス、記述ガイド、公開サイトをライブプロジェクトから管理・エクスポートしたいなら Apidog CLI
重要なのは、生成コマンドをCIに組み込むことです。一度設定すれば、仕様やプロジェクトが変わるたびにドキュメントを自動再生成できます。
ApidogをダウンロードしてCLIを導入し、プロジェクトでエクスポートフローを試してください。詳細はApidogも参照してください。
Top comments (0)