ドキュメント作成をやめよう：AIがライブトラフィックからAPIスキーマを自動生成する方法

長年の開発者の不満 — 「ドキュメントがまた古くなっている」 — に、ついに終止符が打たれつつあります。これは、より厳格な規律やプロセスの改善ではなく、ドキュメントの作り方そのものが根本的に変わることによるものです。

私たちは、ドキュメントを書くことから、その存在を*観測*することへと移行しています。

---

ドキュメントの危機は現実であり、その数字が証明しています

APIドキュメントは、ソフトウェアプロジェクトの未払いの技術的負債として長らく存在してきました。しかし、その規模は否定できないものとなっています。

Postmanの2025年APIの現状レポートは、何千もの開発者を対象に調査し、93%のAPIチームがコラボレーションの障壁に直面していると報告しています。その最も一般的な原因は、一貫性のない、古くなった、または欠落したドキュメントです。仕様書がConfluenceにあり、フィードバックがSlackで行われ、例が個人のGitHubリポジトリに埋もれていると、コンテキストが失われてしまいます。その結果、APIの実態を理解するために毎回宝探しをしている状態です。

同じレポートの2024年版では、39%の開発者が一貫性のないドキュメントをAPI作業の最大の障壁と見なしており、58%のチームが内部ドキュメントツールに依存しているにもかかわらず、ドキュメントは崩壊し続けています。さらに、44%の開発者はAPIの挙動を理解するためにソースコードを直接掘り返すことを余儀なくされています。

この問題は、動機の問題ではなく構造的な問題です。開発者は怠けているわけではなく、ただ速いだけです。手動のドキュメント作成は、CI/CDの速度に追いつきません。

---

失敗した3つのアプローチ

成功している方法に進む前に、何がうまくいかなかったのか正直に振り返る価値があります。

コードファーストのアノテーション — コントローラーに@Schemaや@ApiResponseタグを付ける方法は、ソースコードを膨らませ、ドキュメントの正確さと開発者の規律を密接に結びつけました。しかし、締め切りのプレッシャー下でロジックが変わると、アノテーションはほとんど追従しませんでした。

設計ファーストのYAML — コードの前にOpenAPI仕様を書き、その後に仕様からドキュメントを生成する方法は、アーキテクチャ的にはエレガントでしたが、運用上は脆弱でした。仕様がボトルネックとなり、締め切りに追われる開発者は仕様に記載されていない機能をリリースし、コードが本番環境に到達した瞬間にズレが生じました。

Postmanコレクション — テストには優れていますが、正式な契約としては弱いものでした。不完全でエッジケースを見逃しやすく、自動化されたクライアント生成やコンプライアンスレビューに必要な構造的厳密さに欠けていました。

2024年のPostmanレポートは明確に述べています：”APIはもはや後付けではなく、開発の基盤となっており、平均的なアプリケーションは26から50のAPIを支えています。” この規模のAPI表面積は手作業では維持できません。

---

変化の方向性：タスクとしてのドキュメントから観測としてのドキュメントへ

2025年と2026年に本格的に普及し始めているアプローチはトラフィックベースのAPIドキュメントです。ライブまたはプレプロダクションのトラフィックから直接OpenAPIやPostman仕様を生成し、開発者のアノテーションや手動で管理されたYAMLからではなくなっています。

この手法の代表例はLevo.aiです。これはeBPF（Extended Berkeley Packet Filter）を利用しており、Datadog、New Relic、Palo Alto Networks、Cilium、Sysdigと同じカーネルレベルの技術を使って、コード変更やSDKの統合、設定変更、サイドカーのプロキシなしでAPIトラフィックを受動的にキャプチャします。

実際の仕組みは次の通りです：

1. カーネルレベルでのパッシブトラフィックキャプチャ

LevoのeBPFセンサーは、Kubernetes用のHelm Chartまたは他の環境向けのDockerコマンド一つでインストール可能です。インストール後、REST、GraphQL、gRPC、SOAPを含むすべてのAPIリクエストとレスポンスを、負荷に影響を与えることなくキャプチャします。

eBPFはLinuxカーネルレベルで動作するため、言語やフレームワークに依存しません。Django、Spring Boot、Expressなどのバックエンドに関係なく、ネットワークトラフィックが真実を語ります。

2. 収集したペイロードからのスキーマ推論

システムはキャプチャしたトラフィックを分析し、型、必須・任意のフィールド、認証スキーム、ステータスコードパターン、エラー構造を推測します。例えば、"created_at": "2026-04-05T14:30:00Z"が繰り返し現れる場合、それをISO 8601の日付時刻と識別します。IDにusr_のプレフィックスが一貫して付いている場合、そのパターンを捉えます。同じエンドポイントの複数の観測から、常に現れるフィールドと条件付きで現れるフィールドを区別します。

3. AI強化されたメタデータを含むOpenAPI仕様の生成

十分なトラフィックが観測されると、プラットフォームはエンドポイントのパス、HTTPメソッド、リクエスト・レスポンスのスキーマ、クエリパラメータの型、認証要件、レートリミット情報、ステータスコード、エラーパターンを含むOpenAPI準拠の仕様を生成します。Levoは、このアプローチにより手動で維持される仕様と比べて最大95%のドキュメントの正確さ向上と、一般的に問題となる20〜30%のズレを削減できると報告しています。

重要なのは、AIが生成した人間が読める要約が各エンドポイントに付加されることです。フィールド名や型だけでなく、そのエンドポイントの役割や使い方に関するコンテキストも含まれます。これにより、開発者（またはAIエージェント）が実際に行動できるドキュメントとなります。

4. 環境外に出る前のPII検出

ペイロードデータが分析される前に、スクラビング層がメールアドレスやクレジットカード番号、パスワードなどのPII、PSI、PHIを特定しマスクします。Levoのアーキテクチャは、データの1%未満だけがSaaSプラットフォームに送信され、PIIは環境外に出ません。メタデータとOpenAPI仕様のみが送信されます。

---

開発者のノートパソコン利用ケース

見落とされがちな重要なポイント：このアプローチは本番やステージングだけでなく、ローカル環境でも機能します。

Levoの開発者ノートパソコンサポートは無料のティアとして提供されており、macOSやWindowsにDocker Composeをインストールし、ブラウザやAPIクライアントをローカルセンサーに向けるだけで、OpenAPI仕様を自動生成します。JestやPytest、統合テストスイートを実行すると、そのトラフィックが自動的にドキュメントを構築します。

これにより、ドキュメントは開発段階で生成されるため、マージ前やステージング前、本番前に作成されます。仕様はテストを書く副産物であり、別の成果物ではありません。

---

全体のツールランドスケープ

トラフィックベースの生成は一つのアプローチですが、AIドキュメントエコシステムは大きく拡大しています。2026年に注目すべきツールは以下の通りです：

Levo.ai — 最も技術的に厳格なトラフィックベースのソリューション。シャドーAPI（未ドキュメントのエンドポイントでトラフィックを受け取るもの）、ゾンビAPI（廃止されたエンドポイントで呼び出され続けるもの）、内部APIも自動発見します。GitHub、GitLab、Jenkins、Jira、AWS API Gateway、Postman、Burp Suiteと連携。PCI、HIPAA、ISO 27001のコンプライアンスも強力です。

Apidog — 設計ファーストのアプローチ：APIを設計し、そのライブ仕様から自動的にドキュメントを生成します。REST、GraphQL、WebSocket、gRPC、SOAP、Server-Sent Eventsをサポート。PostmanやSwagger Editor、Swagger UI、Stoplight、モックツールの代替となるプラットフォームです。無料プランあり、有料プランは$12/ユーザー/月から。

Mintlify — Cursor、Perplexity、Coinbase、Anthropicなどの企業に選ばれるドキュメントプラットフォーム。AIネイティブでgit同期、WYSIWYG編集、/llms.txt経由のLLM最適化出力、APIドキュメントをAIコーディングアシスタントに直接アクセス可能なMCPサーバー生成機能を備え、開発者体験を最優先しています。

Ferndesk — FernというAIエージェントがコードベース、サポートチケット、チェンジログ、製品動画を読み込み、ドキュメントを継続的に作成・更新します。6時間ごとにOpenAPI仕様を自動同期し、Swagger 2.0をOpenAPI 3.xに自動アップグレードします。

Knowl.ai — GitHub、Bitbucket、GitLabからコードを直接読み込み、コード変更に合わせてドキュメントを更新します。継続的かつコードベースに統合された仕組みです。

---

エージェント対応性の次元

この変化には、開発者の利便性を超えた側面があります。

Postmanの2025年APIの現状レポートによると、51%の組織がすでにAIエージェントを導入済みで、さらに35%が2年以内に導入予定です。AIエージェントは人間のようにドキュメントを読むのではなく、パラメータを解析し、API呼び出しを自律的に行います。これにより、ドキュメントの品質基準が大きく変わります。古いまたは不完全な仕様から動作するエージェントは、間違ったエンドポイントを呼び出したり、誤ったパラメータを渡したり、エラー状態を正しく処理できなくなります。仕様はもはや人間のためのリファレンスではなく、自律システムの指示セットです。

2025年のPostmanレポートでは、89%の開発者が日常的に生成AIツールを使用し、41%がAPIドキュメント生成にAIツールを利用していると報告しています。しかし、ソースコードに対して動作する言語モデルによるAI生成ドキュメントは、正確にアノテーションされ最新である必要があります。トラフィックベースの生成はこれを完全に回避し、仕様は実際にAPIが何をしているかを反映します。これは、6ヶ月前に誰かが書いた内容ではありません。

Mintlifyはこれを端的に表現しています：最高のAPIドキュメントは、人間がスキミングできるものであり、エージェントが機械的に読めるものでなければならない。/llms.txtに公開し、仕様のためのMCPサーバーを生成するツールは、APIをAIシステムにとっても自然に消費できるものにしています。

---

実践における意味

ワークフローは、ドキュメントの段階から、開発とテストの自然な副産物としてのドキュメントへと変化しています。

統合テストを実行すれば、そのトラフィックが仕様を生成します。リリースすれば仕様は更新されます。まだトラフィックを受け取るエンドポイントを廃止しても、システムはそれを検知します — YAMLファイルを更新するのを誰かが忘れたからではなく、ネットワークが真実を語るからです。

Levoは、このアプローチにより、従来のドキュメント作成に費やしていた開発者の時間の30〜50%を取り戻し、常に正確で最新の仕様によりパートナーのオンボーディング時間を最大40%短縮できると見積もっています。

ドキュメントの危機は、努力の問題ではありませんでした。それはタイミングの問題でした。ドキュメントは常に後から書かれ、別の人が、別のツールで、動くターゲットに向かって書いていたのです。トラフィックベースのAI強化ドキュメント生成は、そのギャップを完全に埋めます。

仕様は、現実の継続的な反映となる — なぜなら、それは現実から構築されているからです。

---

従来のドキュメントとトラフィックベースのドキュメントの比較

次元	従来（手動/アノテーション）	トラフィックベース（AI観測）
労力	高い — エンドポイントごとに開発者の時間が必要	ほぼゼロ — テストと本番トラフィックから自動生成
正確性	ドリフトしやすい；意図を反映、挙動を反映しない	実際の通信挙動を反映
更新頻度	手動；リリース後は忘れられがち	継続的 — デプロイごとに更新
シャドーAPIのカバレッジ	なし	全て — 未ドキュメントのエンドポイントも自動発見
PIIの取り扱い	手動レビュー必要	スキーマ推論前に自動スクラビング
エージェント対応性	人間の完全性に依存	生成時点から構造化・機械可読
セキュリティ	別途監査プロセス	組み込み — 設定ミスも自動検知

---

まずは始めてみよう

トラフィックベースのドキュメントを今すぐ試したい場合:

• Levo.ai は無料の永続ティアを提供しており、macOSやWindowsにDocker Composeをインストールし、ローカルテストやAPIクライアントを使うだけで、OpenAPI仕様を自動生成します。コード変更不要。
• Apidog は、設計ファーストのアプローチを採用し、API設計から自動的にドキュメントを生成するフル機能の無料プランを提供しています。
• Mintlify は、既存の仕様を美しく公開し、AIアクセス可能にするのに最適です。

もはや、ドキュメントが自動化されるかどうかの問題ではありません。あなたのAPIドキュメントが遅れすぎて負担になる前に、その変革を起こすかどうかの問題です。

ドキュメント作成をやめて、観測を始めましょう。