APIドキュメントは、誰かが仕様を編集し、リファレンスの再生成を忘れた瞬間に古くなります。この問題の解決策は、ドキュメント作成を手動ステップとして扱うのをやめることです。単一のコマンドでドキュメントを生成できれば、そのコマンドをCIに組み込み、マージごとに実行させることができます。
ターミナルから行うことには他にも利点があります。コマンドはスクリプト化可能で、レビュー可能な差分を残し、AIエージェントやCIランナーがブラウザを開かずにそれらをトリガーできます。GUIでのクリック操作も、「エクスポートを忘れずに押しましたか」という確認も不要です。
このガイドでは、まず一般的なオープンルートを紹介します。OpenAPIファイルを単一のコマンドでスタンドアロンのHTMLリファレンスまたはMarkdownファイルに変換する方法です。次に、Apidog CLIルートについて詳しく説明します。これはライブプロジェクトからドキュメントを直接抽出し、真の情報源と出力が同期された状態を保ちます。この分野の背景について詳しく知りたい場合は、トップREST APIドキュメンテーションツールのまとめと、知っておくべき無料APIドキュメンテーションツールをご覧ください。
続けていくために必要なものは1つだけです。OpenAPI 3.xファイルです。これらのコマンドのほとんどは、openapi.yamlまたはopenapi.jsonを互換的に受け入れます。
Redocly CLIでHTMLリファレンスを構築する
Redocly CLIは、OpenAPI記述を洗練された自己完結型HTMLページに変換する最速の方法です。これはRedocで仕様をレンダリングし、すべて（スタイル、スクリプト、コンテンツ）を1つのファイルに書き込み、どこにでもホストしたり、チームメイトにメールで送ったりできます。
グローバルにインストールするか、インストールをスキップしてnpxで実行します。
npm install @redocly/cli -g
次に、仕様を指し示します。
redocly build-docs openapi.yaml
デフォルトでは、これにより現在のディレクトリにredoc-static.htmlが書き込まれます。そのファイルをブラウザで開くと、完全な3パネルAPIリファレンスが表示されます。ファイル名またはパスを制御するには、--outputを使用します。
redocly build-docs openapi.yaml --output docs/index.html
これがワークフローの全体です。1つの入力ファイル、1つのコマンド、1つのHTML成果物。Swagger 2.0およびOpenAPI 3.0/3.1記述に対応しているため、既存のほとんどの仕様は変更なしでレンダリングされます。トレードオフはスコープです。build-docsはリファレンスページのみを提供し、それ以上は提供しません。長文のガイド、チュートリアル、入門ページはこれの範囲外です。
WiddershinsでMarkdownを生成する
HTMLを必要としない場合もあります。ドキュメントサイト、静的サイトジェネレーター、またはリポジトリのdocs/フォルダーにドロップできるMarkdownが必要な場合もあります。Widdershinsは、OpenAPI、Swagger、またはAsyncAPIの定義をSlate互換のMarkdownに変換します。
npmからインストールします。
npm install -g widdershins
次に、仕様を変換し、-oで出力をファイルに送信します。
widdershins openapi.yaml -o api.md
-oを省略すると、Widdershinsはstdoutに出力します。これは、どこかにパイプする場合に便利です。コードサンプル用の言語タブを切り替えることもできます。
widdershins openapi.yaml --language_tabs 'shell:cURL' 'python:Python' -o api.md
Widdershinsは、ドキュメントパイプラインがMarkdownファーストである場合に適しています。より広範なMarkdownエクスポートフローを構築している場合は、APIドキュメントジェネレーターをMarkdownエクスポートで使用する方法に関するガイドが周辺ツールをカバーしています。RedoclyとWiddershinsの両方に共通の欠点があります。それは静的ファイルを読み取ることです。API定義がデザインツールにあり、ディスク上のファイルと乖離している場合、古い仕様をドキュメント化していることになります。
Apidog CLIを使用してライブプロジェクトからドキュメントを作成する
統合されたルートが効果を発揮するのはここです。Apidogはオープンソースではありませんが、無料枠とapidog-cliを組み合わせることで、個別のツールを結合する代わりに、エンドポイント、スキーマ、および記述されたドキュメントがすべて1つのプロジェクトに存在し、CLIがそのプロジェクトからオンデマンドでエクスポートするという代替手段を提供します。チームが編集するソースと同じものをエクスポートが読み取るため、乖離が発生しません。
npmからCLIをインストールします。
npm install -g apidog-cli
初めて設定する場合は、Apidog CLIインストールガイドでNodeのバージョンとPATH設定について説明しています。次に、パーソナルアクセストークンで一度認証します。
apidog login --with-token <TOKEN>
トークンは保存されるため、すべての呼び出しで渡す必要はありません。ここからは、すべてがプロジェクトIDに対して実行されます。実行する前に、任意のコマンドに--helpを追加して、正確なフラグを確認してください。
仕様をプロジェクトにインポートする
APIがすでにOpenAPIファイルに存在する場合は、それをプロジェクトにインポートして、CLIがエクスポートできる状態にします。
apidog import --help
apidog import --project <projectId> --format openapi --file ./openapi.json
apidog importはOpenAPI 3.x、Swagger 2.0、Postman、およびApidog形式を受け入れるため、Postmanコレクションや既存のApidogエクスポートを同じ方法で取り込むことができます。仕様がインポートされると、それは他のすべてが読み取るライブソースとなります。
人間が読めるドキュメントをエクスポートする
これがコアコマンドです。apidog exportはOpenAPI、HTML、Markdown、またはPostmanを書き込むため、まず--helpを実行して、バージョンが出荷する正確な形式と出力フラグを確認し、次にプロジェクトのドキュメントをMarkdownにエクスポートします。
apidog export --help
apidog export --project <projectId> --format markdown --output ./api-docs.md
api-docs.mdを開くと、プロジェクトの現在の状態から生成された完全なリファレンスが表示されます。代わりにHTMLが必要ですか？フラグを1つ変更するだけです。
apidog export --project <projectId> --format html --output ./api-docs.html
下流に渡すためのポータブルな仕様が必要な場合は、OpenAPIにエクスポートし直すこともできます。
apidog export --project <projectId> --format openapi --output ./openapi.json
プロジェクトに複数のサービスが含まれており、その一部のみをドキュメント化したい場合は、エクスポートでスコープを絞り込むことができます。1つのプロジェクトでサービスごとに1つのドキュメントファイルを生成できるため、バージョンのスコープおよびIDフラグについてはapidog export --helpを確認してください。
リファレンスだけでなく、記述されたガイドも管理する
スキーマから生成されたリファレンスは話の半分に過ぎません。もう半分は散文です。入門ガイド、認証ウォークスルー、移行メモなどです。Apidogでは、これらはプロジェクトのドキュメントツリー内にMarkdownドキュメントとして存在し、CLIがdocコマンドグループでそれらを管理します。
まずグループのヘルプを読んで、バージョンが出荷する正確なフラグを使用していることを確認してください。
apidog doc --help
apidog doc list --project <projectId>
そこからのフローは、CLIの他のすべてと同じ形です。プロジェクトに対してコマンドを実行し、JSON結果を読み取り、返されるagentHints.nextStepsに従います。コマンドがJSONペイロードを要求する場合、CLIは期待されるスキーマを出力し、送信する前にファイルがそれに照らして有効であることを検証できるため、失敗した呼び出しではなく、自分のマシン上で不足しているフィールドを検出できます。正確な検証サブコマンドについてはapidog cli-schema --helpを確認してください。
ドキュメントサイトを公開する
リファレンスとガイドが準備できたら、ターミナルから公開ドキュメントも管理できます。2つのコマンドがそれをカバーし、最初にヘルプを読むことで、推測されるフラグを節約できます。
apidog docs-site --help
apidog shared-doc --help
人々を混乱させる命名の注意点として、docはプロジェクトのAPIツリー内のMarkdownドキュメントであり、docs-siteはホストされた公開ドキュメントサイトを管理し、shared-docは共有可能なドキュメントリンクを管理します。UIでクリックして作成するのではなく、ターミナルから定義される公開サイトが必要な場合はdocs-siteを、パートナーに渡すためのリンクが必要な場合はshared-docを使用します。その結果、公開がスクリプト化されたステップになります。仕様が変更されたら、プロジェクトを再インポートまたは編集し、再度公開コマンドを実行すると、ホストされたドキュメントに更新が反映されます。
CIに組み込む
これをCLIから実行する理由は、再現性です。コマンドがローカルで動作すれば、パイプラインでも動作します。プッシュごとにMarkdownリファレンスを再生成してコミットする最小限のGitHub Actionsステップは次のようになります。
- 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 build-docsまたはwiddershinsに置き換えても、形は同じです。ドキュメントは誰かがやることを思い出す雑用ではなく、それ自体を再生成するビルド成果物になります。完全なコマンドリファレンスについては、Apidog CLI完全ガイドを参照してください。
よくある落とし穴
- 間違った、または不足しているプロジェクトID。すべてのApidog
export、doc、およびdocs-site呼び出しには--project <projectId>が必要です。IDはプロジェクト設定にあり、人間が読めるプロジェクト名ではありません。コマンドがプロジェクトに関するエラーを出す場合、それが原因であることがほとんどです。 - CIでトークンが設定されていない。
apidog loginは、それを実行するマシンにトークンを保存します。新しいCIランナーでは保存されたトークンがないため、エクスポートの前に同じジョブでlogin --with-tokenを実行する必要があります。トークンは常にシークレットとして保存し、ワークフローファイルには含めないでください。 - 古いファイルのエクスポート。RedoclyとWiddershinsは、渡されたファイルをそのまま読み取ります。
openapi.yamlが古い場合、ドキュメントも古くなります。これはまさに、Apidogがディスク上のファイルではなくライブプロジェクトからエクスポートすることで回避する乖離です。 --helpを読まずにフラグを推測する。export、doc、docs-site、およびshared-docの正確なフラグは、CLIのバージョンによって異なる場合があります。apidog <command> --helpを実行し、うろ覚えのフラグではなく、それが出力する内容に基づいて作業してください。これは2秒で完了し、失敗したビルドを回避できます。
まとめ
ターミナルからAPIをドキュメント化することは、適切な出力を選択することに帰着します。スタンドアロンのHTMLリファレンスが必要な場合はRedocly CLIを、ドキュメントサイト用のMarkdownが必要な場合はWiddershinsを、そしてリファレンスと記述されたガイド、さらに公開サイトをすべて1つのライブソースからエクスポートしたい場合はApidog CLIを使用してください。最後のオプションは、エクスポートとチームが編集するものが同じプロジェクトであるため、ドキュメントの正確さを保つものです。
ここにあるすべてのコマンドはスクリプト化可能であり、これはそれらすべてがCIに属することを意味します。一度設定すれば、変更があるたびにドキュメントが自動的に再生成されます。ApidogをダウンロードしてCLIを入手し、独自のプロジェクトでエクスポートフローを試すか、ApidogがAPIファーストのワークフローにどのように適合するかについて詳しく読んでください。