api-doc-generator

API Doc Generator

ソースコードから API ドキュメントを生成します。REST API、GraphQL、さまざまなドキュメント形式に対応しています。

ソースコードから API ドキュメントを生成します。REST API、GraphQL、さまざまなドキュメント形式に対応しています。

使用する場面

次の操作をユーザーから依頼されたときに、このスキルを使用します。

• API ドキュメントの生成
• インターフェースドキュメントの作成
• API の説明の作成
• OpenAPI/Swagger 仕様の生成

手順

分析手順

1. API の種類を特定する - REST、GraphQL、RPC など
2. エンドポイント情報を抽出する - URL、メソッド、パラメーター
3. データ構造を分析する - リクエスト／レスポンス形式
4. 認証方式を特定する - API Key、OAuth、JWT など
5. ドキュメントを生成する - 標準形式に従って出力する

ドキュメントの内容

各 API エンドポイントには、次の内容を含めます。

• エンドポイントパス - URL と HTTP メソッド
• 説明 - 機能の説明
• パラメーター - パスパラメーター、クエリパラメーター、リクエストボディ
• レスポンス - 成功時とエラー時のレスポンス例
• 認証 - 認証要件

出力形式

次のドキュメント形式に対応しています。

• Markdown（デフォルト）- templates/api-doc.md テンプレートを使用
• OpenAPI 3.0 YAML
• API Blueprint

Markdown 出力形式には templates/api-doc.md を使用します。

標準テンプレート

## API 文档 / API Documentation

### 端点概览 / Endpoint Overview

| 方法 | 路径 | 描述 |
|------|------|------|
| GET | /api/resource | 获取资源列表 |

### 详细说明 / Details

#### [方法] /path

**描述**: ...

**请求参数**:
| 参数 | 类型 | 必需 | 描述 |
|------|------|------|------|

**请求示例**:
```json
{}
```

**响应示例**:
```json
{}
```

例

入力

from fastapi import FastAPI, HTTPException
from pydantic import BaseModel

app = FastAPI()

class User(BaseModel):
    id: int
    name: str
    email: str

@app.get("/users/{user_id}")
async def get_user(user_id: int) -> User:
    """Get a user by ID."""
    if user_id <= 0:
        raise HTTPException(status_code=404, detail="User not found")
    return User(id=user_id, name="John", email="[email protected]")

@app.post("/users")
async def create_user(user: User) -> User:
    """Create a new user."""
    return user

出力

API ドキュメント

エンドポイントの概要

メソッド	パス	説明
GET	/users/{user_id}	ID でユーザー情報を取得
POST	/users	新しいユーザーを作成

---

GET /users/{user_id}

説明: ユーザー ID でユーザー情報を取得します

パスパラメーター:

パラメーター	型	必須	説明
user_id	integer	✅	ユーザーの一意な識別子

レスポンス 200 - 成功:

{
  "id": 1,
  "name": "John",
  "email": "[email protected]"
}

レスポンス 404 - 見つかりません:

{
  "detail": "User not found"
}

---

POST /users

説明: 新しいユーザーを作成します

リクエストボディ:

フィールド	型	必須	説明
id	integer	✅	ユーザー ID
name	string	✅	ユーザー名
email	string	✅	ユーザーのメールアドレス

リクエスト例:

{
  "id": 1,
  "name": "John",
  "email": "[email protected]"
}

レスポンス 200 - 成功:

{
  "id": 1,
  "name": "John",
  "email": "[email protected]"
}