api-documentation-generator

API ドキュメント生成ツール

概要

コードベースから、明確で包括的な API ドキュメントを自動生成します。このスキルを使えば、エンドポイントの説明、リクエスト／レスポンスの例、認証の詳細、エラー処理、使用ガイドラインを含む、プロフェッショナルなドキュメントを作成できます。

REST API、GraphQL API、WebSocket API に最適です。

このスキルを使う場面

• 新しい API のドキュメントを作成する必要がある場合
• 既存の API ドキュメントを更新する場合
• API のドキュメントが不明瞭な場合
• 新しい開発者に API を紹介する場合
• 外部ユーザー向けの API ドキュメントを準備する場合
• OpenAPI／Swagger 仕様を作成する場合

仕組み

ステップ 1：API 構造を分析する

ドキュメントを実際のソースリビジョン、ルーティング／ミドルウェア／スキーマ、検証済みの例に紐づけてください。不明または推測した動作には印を付け、レート制限、パスワードポリシー、トークンの有効期限、エラーの網羅的な一覧を捏造しないでください。合成データとシークレット用のプレースホルダーを使用してください。公開されているユーザー作成機能では、クライアントが任意に指定した管理者ロールを受け付けないようにしてください。別途認可された管理者用エンドポイントがその権限を検証する場合を除き、管理者ロールは省略してください。生成された OpenAPI の断片には、参照されるスキーマ／レスポンスをすべて含め、仕様の検証も行ってください。インタラクティブな「Try It」の呼び出しは実際の操作にあたるため、承認済みのサンドボックスを使用してください。

まず、API のコードベースを調べ、以下を確認します。

• 利用可能なエンドポイントとルート
• HTTP メソッド（GET、POST、PUT、DELETE など）
• リクエストのパラメーターと本文の構造
• レスポンス形式とステータスコード
• 認証と認可の要件
• エラー処理のパターン

ステップ 2：エンドポイントのドキュメントを生成する

各エンドポイントについて、以下を含むドキュメントを作成します。

エンドポイントの詳細：

• HTTP メソッドと URL パス
• エンドポイントの機能を簡潔に説明
• 認証要件
• レート制限の情報（該当する場合）

リクエスト仕様：

• パスパラメーター
• クエリパラメーター
• リクエストヘッダー
• リクエスト本文のスキーマ（型と検証ルールを含む）

レスポンス仕様：

• 成功時のレスポンス（ステータスコードと本文の構造）
• エラーレスポンス（発生し得るすべてのエラーコード）
• レスポンスヘッダー

コード例：

• cURL コマンド
• JavaScript／TypeScript（fetch／axios）
• Python（requests）
• 必要に応じて、その他の言語

ステップ 3：使用ガイドラインを追加する

以下を含めます。

• はじめに
• 認証の設定
• よくあるユースケース
• ベストプラクティス
• レート制限の詳細
• ページネーションのパターン
• フィルタリングと並べ替えのオプション

ステップ 4：エラー処理をドキュメント化する

以下を含む、分かりやすいエラーのドキュメントを作成します。

• 発生し得るすべてのエラーコード
• エラーメッセージの形式
• トラブルシューティングガイド
• よくあるエラーの状況と解決策

ステップ 5：インタラクティブな例を作成する

可能な場合、以下を提供します。

• Postman コレクション
• OpenAPI／Swagger 仕様
• インタラクティブなコード例
• レスポンスのサンプル

例

例 1：REST API エンドポイントのドキュメント

## Create User

Creates a new user account.

**Endpoint:** `POST /api/v1/users`

**Authentication:** Required (Bearer token)

**Request Body:**
\`\`\`json
{
  "email": "[email protected]",      // Required: Valid email address
  "password": "SecurePass123!",     // Required: Min 8 chars, 1 uppercase, 1 number
  "name": "John Doe",               // Required: 2-50 characters
  "role": "user"                    // Server-assigned output; do not accept admin from public registration
}
\`\`\`

**Success Response (201 Created):**
\`\`\`json
{
  "id": "usr_1234567890",
  "email": "[email protected]",
  "name": "John Doe",
  "role": "user",
  "createdAt": "2026-01-20T10:30:00Z",
  "emailVerified": false
}
\`\`\`

**Error Responses:**

- `400 Bad Request` - Invalid input data
  \`\`\`json
  {
    "error": "VALIDATION_ERROR",
    "message": "Invalid email format",
    "field": "email"
  }
  \`\`\`

- `409 Conflict` - Email already exists
  \`\`\`json
  {
    "error": "EMAIL_EXISTS",
    "message": "An account with this email already exists"
  }
  \`\`\`

- `401 Unauthorized` - Missing or invalid authentication token

**Example Request (cURL):**
\`\`\`bash
curl -X POST https://api.example.com/api/v1/users \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "password": "SecurePass123!",
    "name": "John Doe"
  }'
\`\`\`

**Example Request (JavaScript):**
\`\`\`javascript
const response = await fetch('https://api.example.com/api/v1/users', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    email: '[email protected]',
    password: 'SecurePass123!',
    name: 'John Doe'
  })
});

const user = await response.json();
console.log(user);
\`\`\`

**Example Request (Python):**
\`\`\`python
import requests

response = requests.post(
    'https://api.example.com/api/v1/users',
    headers={
        'Authorization': f'Bearer {token}',
        'Content-Type': 'application/json'
    },
    json={
        'email': '[email protected]',
        'password': 'SecurePass123!',
        'name': 'John Doe'
    }
)

user = response.json()
print(user)
\`\`\`

例 2：GraphQL API のドキュメント

## User Query

Fetch user information by ID.

**Query:**
\`\`\`graphql
query GetUser($id: ID!) {
  user(id: $id) {
    id
    email
    name
    role
    createdAt
    posts {
      id
      title
      publishedAt
    }
  }
}
\`\`\`

**Variables:**
\`\`\`json
{
  "id": "usr_1234567890"
}
\`\`\`

**Response:**
\`\`\`json
{
  "data": {
    "user": {
      "id": "usr_1234567890",
      "email": "[email protected]",
      "name": "John Doe",
      "role": "user",
      "createdAt": "2026-01-20T10:30:00Z",
      "posts": [
        {
          "id": "post_123",
          "title": "My First Post",
          "publishedAt": "2026-01-21T14:00:00Z"
        }
      ]
    }
  }
}
\`\`\`

**Errors:**
\`\`\`json
{
  "errors": [
    {
      "message": "User not found",
      "extensions": {
        "code": "USER_NOT_FOUND",
        "userId": "usr_1234567890"
      }
    }
  ]
}
\`\`\`

例 3：認証のドキュメント

## Authentication

All API requests require authentication using Bearer tokens.

### Getting a Token

**Endpoint:** `POST /api/v1/auth/login`

**Request:**
\`\`\`json
{
  "email": "[email protected]",
  "password": "your-password"
}
\`\`\`

**Response:**
\`\`\`json
{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expiresIn": 3600,
  "refreshToken": "refresh_token_here"
}
\`\`\`

### Using the Token

Include the token in the Authorization header:

\`\`\`
Authorization: Bearer YOUR_TOKEN
\`\`\`

### Token Expiration

Tokens expire after 1 hour. Use the refresh token to get a new access token:

**Endpoint:** `POST /api/v1/auth/refresh`

**Request:**
\`\`\`json
{
  "refreshToken": "refresh_token_here"
}
\`\`\`

ベストプラクティス

✅ 推奨事項

• 一貫性を保つ - すべてのエンドポイントで同じ形式を使用します
• 例を含める - 複数の言語で動作するコード例を提供します
• エラーを記載する - 発生し得るすべてのエラーコードとその意味を列挙します
• 実際のデータを示す - 「foo」や「bar」ではなく、現実的なサンプルデータを使用します
• パラメーターを説明する - 各パラメーターの機能と制約を説明します
• API をバージョン管理する - URL にバージョン番号を含めます（/api/v1/）
• タイムスタンプを追加する - ドキュメントの最終更新日時を示します
• 関連するエンドポイントをリンクする - 関連機能をユーザーが見つけやすくします
• レート制限を記載する - レート制限ポリシーがあれば記載します
• Postman コレクションを提供する - API を簡単にテストできるようにします

❌ してはいけないこと

• エラーケースを省略しない - ユーザーは何が問題になり得るかを知る必要があります
• 曖昧な説明を使わない - 「データを取得します」では役に立ちません
• 認証について忘れない - 認証要件は必ず記載してください
• エッジケースを無視しない - ページネーション、フィルタリング、ソートについて記載してください
• 壊れた例を載せない - すべてのコード例をテストしてください
• 古い情報を使わない - ドキュメントをコードと同期させてください
• 複雑にしすぎない - シンプルでざっと確認しやすい内容にしてください
• レスポンスヘッダーについて忘れない - 重要なヘッダーを記載してください

ドキュメントの構成

推奨セクション

1. 概要

   • API の機能
   • ベース URL
   • API のバージョン
   • サポート窓口

2. 認証

   • 認証方法
   • トークン管理
   • セキュリティのベストプラクティス

3. クイックスタート

   • 開始するための簡単な例
   • よくあるユースケースの手順

4. エンドポイント

   • リソースごとに整理
   • 各エンドポイントの詳細

5. データモデル

   • スキーマ定義
   • フィールドの説明
   • 検証ルール

6. エラー処理

   • エラーコードのリファレンス
   • エラーレスポンスの形式
   • トラブルシューティングガイド

7. レート制限

   • 上限とクォータ
   • 確認すべきヘッダー
   • レート制限エラーへの対処

8. 変更履歴

   • API のバージョン履歴
   • 破壊的変更
   • 非推奨に関する通知

9. SDK とツール

   • 公式クライアントライブラリ
   • Postman コレクション
   • OpenAPI 仕様

よくある落とし穴

問題：ドキュメントが最新の状態に保たれない

症状： 例が動作しない、パラメーターが間違っている、エンドポイントが異なるデータを返す 解決策：

• コードのコメントやアノテーションからドキュメントを生成する
• Swagger/OpenAPI などのツールを使う
• ドキュメントを検証する API テストを追加する
• API を変更するたびにドキュメントをレビューする

問題：エラーに関する説明が不足している

症状： ユーザーがエラーへの対処方法を把握できず、サポートチケットが増える 解決策：

• 考えられるすべてのエラーコードを記載する
• 明確なエラーメッセージを提供する
• トラブルシューティングの手順を含める
• エラーレスポンスの例を示す

問題：例が動作しない

症状： ユーザーが使い始められず、フラストレーションが増す 解決策：

• すべてのコード例をテストする
• 実際に動作するエンドポイントを使う
• 完全な例を含める（断片的なものではなく）
• サンドボックス環境を用意する

問題：パラメーターの要件が不明確

症状： ユーザーが無効なリクエストを送信し、検証エラーが発生する 解決策：

• 必須か任意かを明確に示す
• データ型と形式を記載する
• 検証ルールを示す
• 値の例を提示する

ツールと形式

OpenAPI/Swagger

インタラクティブなドキュメントを生成します：

openapi: 3.0.0
info:
  title: My API
  version: 1.0.0
paths:
  /users:
    post:
      summary: Create a new user
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateUserRequest'

Postman コレクション

テストを簡単に行えるようにコレクションをエクスポートします：

{
  "info": {
    "name": "My API",
    "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json"
  },
  "item": [
    {
      "name": "Create User",
      "request": {
        "method": "POST",
        "url": "{{baseUrl}}/api/v1/users"
      }
    }
  ]
}

関連スキル

• @doc-coauthoring - 共同でドキュメントを作成する場合
• @copywriting - 明確でユーザーにとってわかりやすい説明を書く場合
• @test-driven-development - API の動作がドキュメントと一致していることを確認する場合
• @systematic-debugging - API の問題をトラブルシューティングする場合

追加リソース

• OpenAPI 仕様
• REST API のベストプラクティス
• GraphQL ドキュメント
• API 設計パターン
• Postman ドキュメント

---

プロのヒント： API ドキュメントは、できるだけコードに近い状態に保ちましょう。コードのコメントからドキュメントを生成するツールを使うと、同期を維持できます。

制限事項

• 上記で説明した範囲にタスクが明確に該当する場合にのみ、このスキルを使用してください。
• 出力を、環境固有の検証、テスト、または専門家によるレビューの代わりとして扱わないでください。
• 必要な入力、権限、安全上の境界、または成功基準が不足している場合は、作業を中断して確認を求めてください。