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 エンドポイント ドキュメント

## ユーザーの作成

新しいユーザーアカウントを作成します。

**エンドポイント：** `POST /api/v1/users`

**認証：** 必須 (Bearer トークン)

**リクエストボディ：**
\`\`\`json
{
  "email": "user@example.com",      // 必須: 有効なメールアドレス
  "password": "SecurePass123!",     // 必須: 最小 8 文字、大文字 1 文字、数字 1 文字
  "name": "John Doe",               // 必須: 2～50 文字
  "role": "user"                    // オプション: "user" または "admin" (デフォルト: "user")
}
\`\`\`

**成功レスポンス (201 Created)：**
\`\`\`json
{
  "id": "usr_1234567890",
  "email": "user@example.com",
  "name": "John Doe",
  "role": "user",
  "createdAt": "2026-01-20T10:30:00Z",
  "emailVerified": false
}
\`\`\`

**エラーレスポンス：**

- `400 Bad Request` - 無効な入力データ
  \`\`\`json
  {
    "error": "VALIDATION_ERROR",
    "message": "無効なメール形式です",
    "field": "email"
  }
  \`\`\`

- `409 Conflict` - メールがすでに存在
  \`\`\`json
  {
    "error": "EMAIL_EXISTS",
    "message": "このメールアドレスでアカウントがすでに存在します"
  }
  \`\`\`

- `401 Unauthorized` - 認証トークンが見つからないか無効

**リクエスト例 (cURL)：**
\`\`\`bash
curl -X POST https://api.example.com/api/v1/users \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "password": "SecurePass123!",
    "name": "John Doe"
  }'
\`\`\`

**リクエスト例 (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: 'user@example.com',
    password: 'SecurePass123!',
    name: 'John Doe'
  })
});

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

**リクエスト例 (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': 'user@example.com',
        'password': 'SecurePass123!',
        'name': 'John Doe'
    }
)

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

例 2: GraphQL API ドキュメント

## ユーザークエリ

ID でユーザー情報を取得します。

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

**変数：**
\`\`\`json
{
  "id": "usr_1234567890"
}
\`\`\`

**レスポンス：**
\`\`\`json
{
  "data": {
    "user": {
      "id": "usr_1234567890",
      "email": "user@example.com",
      "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"
        }
      ]
    }
  }
}
\`\`\`

**エラー：**
\`\`\`json
{
  "errors": [
    {
      "message": "ユーザーが見つかりません",
      "extensions": {
        "code": "USER_NOT_FOUND",
        "userId": "usr_1234567890"
      }
    }
  ]
}
\`\`\`

例 3: 認証ドキュメント

## 認証

すべての API リクエストは Bearer トークンを使用した認証が必要です。

### トークンの取得

**エンドポイント：** `POST /api/v1/auth/login`

**リクエスト：**
\`\`\`json
{
  "email": "user@example.com",
  "password": "your-password"
}
\`\`\`

**レスポンス：**
\`\`\`json
{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expiresIn": 3600,
  "refreshToken": "refresh_token_here"
}
\`\`\`

### トークンの使用

Authorization ヘッダーにトークンを含めます：

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

### トークンの有効期限

トークンは 1 時間後に有効期限が切れます。リフレッシュトークンを使用して新しいアクセストークンを取得します：

**エンドポイント：** `POST /api/v1/auth/refresh`

**リクエスト：**
\`\`\`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

---

プロのヒント： API ドキュメントをコードに可能な限り近く保つようにしてください。コードコメントからドキュメントを生成するツールを使用して、同期を保つようにしましょう。

制限事項

• このスキルは、上記で説明されたスコープに明確に一致するタスクの場合にのみ使用してください。
• 出力を環境固有の検証、テスト、またはエキスパートレビューの代わりとして扱わないでください。
• 必須入力、権限、安全な境界線、または成功基準が欠落している場合は、停止して明確にしてください。