api-documentation-generator

API ドキュメントジェネレーター

概要

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

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

このスキルを使用する場面

• 新しい API をドキュメント化する必要があるとき
• 既存の API ドキュメントを更新するとき
• API に明確なドキュメントが欠けているとき
• 新しい開発者を API にオンボーディングするとき
• 外部ユーザー向けに API ドキュメントを準備するとき
• OpenAPI/Swagger 仕様を作成するとき

仕組み

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

まず、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"                    // Optional: "user" or "admin" (default: "user")
}
\`\`\`

**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 Specification
• REST API Best Practices
• GraphQL Documentation
• API Design Patterns
• Postman Documentation

---

Pro Tip: API ドキュメントはできる限りコードの近くで管理してください。コードのコメントからドキュメントを生成するツールを使えば、内容を実装と同期したまま保てます!