カテゴリー 3：コーディング＆テクニカル 4 / 6
中級 Guide 16 Coding API Documentation

APIドキュメント

Claudeで包括的なAPIドキュメントを生成 — エンドポイント、パラメータ、例、エラーハンドリングガイド。

2026年3月25日 10 min read

学べること

  • コードまたは説明から完全で構造化されたAPIドキュメントを生成するためのClaudeへのプロンプト方法
  • OpenAPI/Swaggerの仕様、READMEのエンドポイントセクション、開発者ガイドを生成するテクニック
  • APIが進化するにつれてドキュメントを一貫に保ち更新するためのClaude活用方法

ユースケース

ドキュメントはほぼすべてのチームが遅れるAPI開発の部分です。コードは出荷されます；ドキュメントは遅れます。新しいエンドポイントがエントリなしに追加されます。パラメータが変更されてもドキュメントは更新されません。エラーコードが説明なしに増えます。最終的に、内部または外部のAPIコンシューマーは存在すべきドキュメントを参照する代わりに、試行錯誤でAPIをリバースエンジニアリングしています。

Claudeは、コードの意図を理解して構造化された人間が読める文章に翻訳できるため、APIドキュメントを書く摩擦を劇的に下げます。ルートハンドラー、コントローラー、またはエンドポイントが何をするかの説明を貼り付けると、Claudeはエンドポイントの目的、型と説明を含むすべてのパラメータ、例のリクエストとレスポンス、および呼び出し側が処理すべきエラーケースをカバーするドキュメントを生成します。

これはドキュメントを書くよりも速くAPIを構築するチーム、既存のエンドポイントを素早く理解する必要があるオンボーディング中の新しい開発者、およびSwagger UI、Postmanコレクション、またはSDK生成などのツーリングのためのOpenAPI仕様を生成する必要があるチームに特に価値があります。

ステップバイステップガイド

ステップ1：ドキュメントの形式を決定する

APIドキュメントには異なる目的を持つ複数の形式があります：

  • OpenAPI 3.x YAML/JSON — ツーリングのための機械読み取り可能な仕様（Swagger UI、コード生成、Postmanのインポート）
  • Markdownエンドポイントリファレンス — READMEまたはドキュメントサイトのための人間が読めるドキュメント
  • インラインコードコメント — IDEの統合のためのJSDoc、Pythonのdocstring、Goのdocコメント
  • 開発者ガイドの文章 — 認証、ページネーション、レート制限を説明するナラティブなドキュメント

必要な形式をClaudeに伝えましょう。各々は異なる構造と詳細が必要です。

ステップ2：ソース素材を提供する

Claudeに以下の開始点の一つを与えましょう：

オプションA — ルートハンドラーまたはコントローラーコードを貼り付ける： これが最も信頼性の高いアプローチです。Claudeは実際の実装を読んで、どのフィールドがオプションかを含めてそれが何をするかを文書化できます。

オプションB — エンドポイントを平易な言語で説明する： コードがまだない場合（またはClaudeが苦手な言語の場合）、エンドポイントを説明しましょう：メソッド、パス、認証要件、各パラメータが何をするか、成功はどのように見えるか、どのエラーが発生しうるか。

オプションC — 既存の不完全なドキュメントを貼り付けて拡張を依頼する： 「これは部分的なエンドポイントの説明です。完全にしてください——欠けているパラメータを追加し、エラー表を埋め、リクエスト/レスポンスの例を追加してください。」

ステップ3：あなたのコンテキストで「完全」が何を意味するかを指定する

異なる読者は異なるレベルの詳細が必要です。Claudeに伝えましょう：

  • 誰が読むか？（外部開発者、内部エンジニア、ジュニア開発者）
  • curlの例が必要か？JavaScriptのfetchか？Pythonのrequestsか？
  • エラーコードを表として文書化すべきか？
  • 認証の指示が必要か？

例：「これは外部開発者向けの公開されたドキュメントです。含めること：エンドポイントの説明、型と必須/オプションを含むすべてのパス/クエリ/ボディパラメータ、curlの例、JSONレスポンスの例、および考えられるすべてのHTTPエラーコードと説明の表。」

ステップ4：OpenAPI仕様を生成する

機械読み取り可能な仕様については、Claudeに直接依頼しましょう：

「このエンドポイントのOpenAPI 3.0仕様をYAMLで生成してください。」

ルートハンドラーを提供すると、Claudeはパス、operationId、パラメータ、requestBodyスキーマ、レスポンススキーマを含む適切に構造化された仕様を生成します。これをSwagger Editorに貼り付けて検証したり、既存の仕様ファイルに追加したりできます。

ステップ5：APIが変更されるにつれてドキュメントを維持する

エンドポイントが変更されたら、更新されたコードと古いドキュメントを並べて貼り付けましょう：

「これが更新されたルートハンドラーと既存のドキュメントです。変更を反映してドキュメントを更新してください——新しいパラメータsort_by、limitのデフォルトが20から50に変更、新しい422エラーケース。」

この増分的な更新ワークフローにより、ゼロから書き直すことなくドキュメントを同期させます。

プロンプトテンプレート

以下のエンドポイントのAPIドキュメントを生成してください。

形式：[OpenAPI 3.0 YAML / Markdownリファレンス / JSDocコメント / など]
読者：[内部エンジニア / 外部開発者 / など]

エンドポイントの詳細：
[ルートハンドラーコードを貼り付けるか、以下を説明してください：]
- メソッド：[GET / POST / PUT / DELETE / など]
- パス：[例：/api/v1/users/{id}]
- 認証：[Bearerトークン / APIキー / なし]
- 説明：[このエンドポイントが何をするか]
- パスパラメータ：[型付きリスト]
- クエリパラメータ：[型、必須/オプション、デフォルト付きリスト]
- リクエストボディ：[JSONスキーマまたはフィールドの説明]
- 成功レスポンス：[ステータスコード、ボディ構造]
- エラーレスポンス：[ステータスコードとそれが発生するとき]

含めること：
- [ ] 型と必須/オプションを含むパラメータの説明
- [ ] curlリクエストの例
- [ ] JSONレスポンスの例
- [ ] エラーコードの表

ヒントとベストプラクティス

  1. スキーマだけでなく実際のリクエストとレスポンスの例を含める — 開発者は抽象的な型の説明よりも具体的な例から速く学びます。常にClaudeにスキーマとともに実際の例を含めるよう依頼しましょう。「stringや1234のようなプレースホルダー値ではなく、実際に見えるようなサンプルデータを使ってください。」

  2. Claudeにコードの曖昧さにフラグを立てるよう依頼する — コードからドキュメントを生成する際に追加しましょう：*「実装に不明なことや直接読むのではなく推測した必要があることがあれば、私が確認できるようにフラグを立ててください。」*これにより、Claudeが意図した動作を推測しなければならなかった場合を見つけます。

  3. エラーケースを徹底的に文書化する — ほとんどのAPIドキュメントはハッピーパスを過剰に文書化し、エラーを十分に文書化しません。明示的に依頼しましょう：「各エラーケースについて、説明してください：HTTPステータスコード、エラーレスポンスボディ構造、エラーを引き起こしたもの、呼び出し側が何をすべきか。」

  4. 認証セクションを一度書いてから再利用する — 認証はすべてのエンドポイントで同じです。Claudeに徹底的な認証セクションを一度書くよう依頼し、すべてのエンドポイントで繰り返すのではなくそのセクションを参照するよう伝えましょう。

  5. ドキュメントとともにPostmanコレクションを生成する — OpenAPI YAMLを生成した後、依頼しましょう：*「同じリクエスト例でこのエンドポイントのPostmanコレクションJSONも生成してください。」*これにより、開発者は読むだけでなく、すぐにインポートしてテストできるものが得られます。

試してみよう

コードベースでドキュメントがないか不十分なドキュメントのAPIエンドポイントを見つけましょう。ルートハンドラーをClaudeに以下のプロンプトで貼り付けましょう：

「このエンドポイントの完全なMarkdown APIリファレンスを生成してください。含めること：1文の説明、パラメータ表（名前、型、必須、説明）、実際のデータに見えるcurlの例、成功レスポンスの例、エラーコードと説明の表。」

結果をプロジェクトのREADMEまたはドキュメントフォルダに追加して、新しいチームメンバーがそのエンドポイントをどれほど速く理解して使えるかを確認しましょう。