api-documenter

API ドキュメント生成スキル

コードから API ドキュメントを自動生成します。

起動するタイミング

• ✅ API エンドポイントが追加・変更されたとき
• ✅ ユーザーが API ドキュメント、OpenAPI、Swagger に言及したとき
• ✅ ルートファイルが変更されたとき
• ✅ コントローラーファイルが変更されたとき
• ✅ ドキュメントが必要なとき

生成するもの

OpenAPI 3.0 仕様

• エンドポイントの説明
• リクエスト／レスポンスのスキーマ
• 認証要件
• ペイロードの例
• エラーレスポンス

対応フォーマット

• OpenAPI 3.0（JSON/YAML）
• Swagger 2.0
• API Blueprint
• RAML

例

Express.js エンドポイント

// You write:
/**
 * Get user by ID
 * @param {string} id - User ID
 * @returns {User} User object
 */
app.get('/api/users/:id', async (req, res) => {
  const user = await User.findById(req.params.id);
  res.json(user);
});

// I auto-generate OpenAPI spec:
paths:
  /api/users/{id}:
    get:
      summary: Get user by ID
      parameters:
        - name: id
          in: path
          required: true
          description: User ID
          schema:
            type: string
      responses:
        '200':
          description: User found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
              example:
                id: "123"
                name: "John Doe"
                email: "[email protected]"
        '404':
          description: User not found

FastAPI エンドポイント

# You write:
@app.get("/users/{user_id}")
def get_user(user_id: int) -> User:
    """Get user by ID"""
    return db.query(User).filter(User.id == user_id).first()

// I auto-generate:
paths:
  /users/{user_id}:
    get:
      summary: Get user by ID
      parameters:
        - name: user_id
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'

OpenAPI ドキュメント一式

openapi: 3.0.0
info:
  title: User API
  version: 1.0.0
  description: API for user management

servers:
  - url: https://api.example.com/v1

paths:
  /api/users:
    get:
      summary: List all users
      responses:
        '200':
          description: Users array
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/User'

components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        email:
          type: string
          format: email

検出ロジック

フレームワークの検出

以下のフレームワークを自動的に認識します。

• Express.js（Node.js）
• FastAPI（Python）
• Django REST（Python）
• Spring Boot（Java）
• Gin（Go）
• Rails（Ruby）

コメントの解析

以下からドキュメントを抽出します。

• JSDoc コメント（/** */）
• Python の docstring
• JavaDoc
• デコレーター付きのインラインコメント

ドキュメントの拡充

不足している情報

// Your code:
app.post('/api/users', (req, res) => {
  User.create(req.body);
});

// I suggest additions:
/**
 * Create new user
 * @param {Object} req.body - User data
 * @param {string} req.body.name - User name (required)
 * @param {string} req.body.email - User email (required)
 * @returns {User} Created user
 * @throws {400} Invalid input
 * @throws {409} Email already exists
 */

例の生成

現実的な例を生成します。

{
  "id": "usr_1234567890",
  "name": "John Doe",
  "email": "[email protected]",
  "createdAt": "2025-10-24T10:30:00Z",
  "verified": true
}

@docs-writer との連携

自分（スキル）： コードから API 仕様を自動生成します @docs-writer（サブエージェント）： 包括的なユーザーガイドとチュートリアルを作成します

ワークフロー

1. OpenAPI 仕様を生成します
2. ユーザーガイドが必要な場合 → @docs-writer サブエージェントを呼び出します
3. サブエージェントがドキュメントサイト一式を作成します

統合

Swagger UI との連携

// app.js
const swaggerUi = require('swagger-ui-express');
const spec = require('./openapi.json'); // Generated by skill

app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(spec));

Postman との連携

生成した OpenAPI 仕様をエクスポートします。

# Import into Postman for API testing
File → Import → openapi.json

ドキュメントサイトとの連携

• Docusaurus：API ドキュメント用プラグイン
• MkDocs：OpenAPI プラグイン
• Redoc：OpenAPI レンダラー
• Stoplight：API 設計プラットフォーム

カスタマイズ

会社固有のドキュメント標準を追加します。

cp -r ~/.claude/skills/documentation/api-documenter \
      ~/.claude/skills/documentation/company-api-documenter

# Edit to add:
# - Company API standards
# - Custom response formats
# - Internal schemas

サンドボックスとの互換性

サンドボックスなしで動作： ✅ はい サンドボックスありで動作： ✅ はい

• ファイルシステム：OpenAPI ファイルを書き込みます
• ネットワーク：不要です
• 設定：不要です

ベストプラクティス

1. コメントを最新に保つ - ドキュメントはコードに沿って更新されます
2. 型ヒントを使う - TypeScript や Python の型が役立ちます
3. 例を含める - 実際のリクエスト／レスポンスを記載します
4. エラーを文書化する - 起こりうるすべてのエラーレスポンスを記載します
5. API にバージョンを付ける - エンドポイントにバージョンを含めます

関連ツール

• @docs-writer サブエージェント：ユーザーガイドとチュートリアル
• readme-updater スキル：README を最新の状態に保ちます
• /docs-gen コマンド：ドキュメントを一式生成します