Imported from MikeCheng1208/BattleTree (.agents/skills/api-docs-generator/SKILL.md). Install upstream with npx skills add MikeCheng1208/BattleTree --skill api-docs-generator. Copyright stays with the author.

API Documentation Generator Skill

APIドキュメントを自動生成するスキルです。

概要

このスキルは、ソースコードから美しく、詳細で、インタラクティブなAPIドキュメントを自動生成します。OpenAPI/Swagger、Markdown、HTML、Postman Collection等の多様な形式に対応し、開発者に優しいドキュメントを作成します。

主な機能

• OpenAPI/Swagger仕様生成: REST APIの標準仕様
• Markdown形式: GitHub/GitLab対応
• インタラクティブHTML: 試せるAPIドキュメント
• Postman Collection: インポート可能なコレクション
• GraphQL Schema: GraphQL APIのドキュメント
• コード例生成: 複数言語のクライアントコード
• 認証ドキュメント: OAuth、JWT、API Key等の説明
• エラーコードリファレンス: 包括的なエラー情報
• レート制限情報: 制限とベストプラクティス
• バージョニング: API バージョン管理

サポートフレームワーク

REST API

• Express.js (Node.js)
• FastAPI (Python)
• Flask (Python)
• Django REST Framework (Python)
• Spring Boot (Java)
• ASP.NET Core (C#)
• Gin/Echo (Go)
• Rails (Ruby)
• Laravel (PHP)

GraphQL

• Apollo Server
• GraphQL Yoga
• Hasura

使用方法

基本的なドキュメント生成

このAPIエンドポイントのドキュメントを生成：

GET /api/users/{id}

実装コード:
[コードを貼り付け]

形式: OpenAPI 3.0

コントローラー全体

このコントローラーの完全なAPIドキュメントを生成：
- すべてのエンドポイント
- リクエスト/レスポンス例
- エラーケース
- 認証要件

[コントローラーコード]

プロジェクト全体

プロジェクト全体のAPIドキュメントを生成：
フレームワーク: Express.js
出力形式: OpenAPI 3.0 + Swagger UI
含める内容:
- 認証フロー
- すべてのエンドポイント
- データモデル
- エラーコード

出力形式

1. OpenAPI/Swagger 3.0

openapi: 3.0.0
info:
  title: User Management API
  description: API for managing users in the system
  version: 1.0.0
  contact:
    name: API Support
    email: support@example.com

servers:
  - url: https://api.example.com/v1
    description: Production server
  - url: https://staging-api.example.com/v1
    description: Staging server

paths:
  /users:
    get:
      summary: Get all users
      description: Retrieve a paginated list of users
      tags:
        - Users
      parameters:
        - name: page
          in: query
          description: Page number (starts at 1)
          required: false
          schema:
            type: integer
            default: 1
            minimum: 1
        - name: limit
          in: query
          description: Number of items per page
          required: false
          schema:
            type: integer
            default: 20
            minimum: 1
            maximum: 100
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/User'
                  pagination:
                    $ref: '#/components/schemas/Pagination'
              examples:
                success:
                  value:
                    data:
                      - id: 1
                        name: John Doe
                        email: john@example.com
                        created_at: "2024-01-15T10:30:00Z"
                      - id: 2
                        name: Jane Smith
                        email: jane@example.com
                        created_at: "2024-01-16T14:20:00Z"
                    pagination:
                      page: 1
                      limit: 20
                      total: 2
                      total_pages: 1
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - bearerAuth: []

    post:
      summary: Create a new user
      description: Create a new user with the provided information
      tags:
        - Users
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - name
                - email
                - password
              properties:
                name:
                  type: string
                  minLength: 2
                  maxLength: 100
                  example: John Doe
                email:
                  type: string
                  format: email
                  example: john@example.com
                password:
                  type: string
                  format: password
                  minLength: 8
                  example: SecurePass123!
            examples:
              user:
                value:
                  name: John Doe
                  email: john@example.com
                  password: SecurePass123!
      responses:
        '201':
          description: User created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '400':
          $ref: '#/components/responses/BadRequest'
        '409':
          description: Email already exists
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /users/{id}:
    get:
      summary: Get user by ID
      tags:
        - Users
      parameters:
        - name: id
          in: path
          required: true
          description: User ID
          schema:
            type: integer
      responses:
        '200':
          description: User found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '404':
          $ref: '#/components/responses/NotFound'

components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: integer
          readOnly: true
        name:
          type: string
        email:
          type: string
          format: email
        created_at:
          type: string
          format: date-time
          readOnly: true
        updated_at:
          type: string
          format: date-time
          readOnly: true

    Pagination:
      type: object
      properties:
        page:
          type: integer
        limit:
          type: integer
        total:
          type: integer
        total_pages:
          type: integer

    Error:
      type: object
      properties:
        error:
          type: string
        message:
          type: string
        details:
          type: array
          items:
            type: object

  responses:
    BadRequest:
      description: Bad request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'

    Unauthorized:
      description: Unauthorized
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'

    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'

    InternalServerError:
      description: Internal server error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'

  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

2. Markdown形式

# User Management API Documentation

Version: 1.0.0

Base URL: `https://api.example.com/v1`

## Authentication

This API uses JWT Bearer token authentication.

Include the token in the Authorization header:

Authorization: Bearer

To obtain a token, use the `/auth/login` endpoint.

## Endpoints

### Get All Users

Retrieve a paginated list of users.

**Endpoint:** `GET /users`

**Authentication:** Required

**Query Parameters:**

| Parameter | Type    | Required | Default | Description                |
|-----------|---------|----------|---------|----------------------------|
| page      | integer | No       | 1       | Page number (starts at 1)  |
| limit     | integer | No       | 20      | Items per page (max: 100)  |

**Example Request:**

```bash
curl -X GET "https://api.example.com/v1/users?page=1&limit=20" \
  -H "Authorization: Bearer your-token-here"

Success Response (200 OK):

{
  "data": [
    {
      "id": 1,
      "name": "John Doe",
      "email": "john@example.com",
      "created_at": "2024-01-15T10:30:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 50,
    "total_pages": 3
  }
}

Error Responses:

• 400 Bad Request: Invalid parameters
• 401 Unauthorized: Missing or invalid token
• 500 Internal Server Error: Server error

Create User

Create a new user account.

Endpoint: POST /users

Authentication: Admin only

Request Body:

{
  "name": "John Doe",
  "email": "john@example.com",
  "password": "SecurePass123!"
}

Field Validation:

Example Request:

curl -X POST "https://api.example.com/v1/users" \
  -H "Authorization: Bearer your-admin-token" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "John Doe",
    "email": "john@example.com",
    "password": "SecurePass123!"
  }'

Success Response (201 Created):

{
  "id": 123,
  "name": "John Doe",
  "email": "john@example.com",
  "created_at": "2024-01-20T15:30:00Z"
}

Error Responses:

• 400 Bad Request: Invalid input data
• 409 Conflict: Email already exists
• 401 Unauthorized: Not authenticated
• 403 Forbidden: Insufficient permissions

Error Codes

Rate Limiting

• Limit: 1000 requests per hour per API key
• Headers: Check X-RateLimit-* headers in responses
• Exceeded: Returns 429 Too Many Requests

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 950
X-RateLimit-Reset: 1642684800

### 3. インタラクティブHTML (Swagger UI)

```html
<!DOCTYPE html>
<html>
<head>
  <title>API Documentation</title>
  <link rel="stylesheet" href="https://unpkg.com/swagger-ui-dist@5/swagger-ui.css" />
</head>
<body>
  <div id="swagger-ui"></div>
  <script src="https://unpkg.com/swagger-ui-dist@5/swagger-ui-bundle.js"></script>
  <script>
    window.onload = function() {
      SwaggerUIBundle({
        url: "openapi.yaml",
        dom_id: '#swagger-ui',
        presets: [
          SwaggerUIBundle.presets.apis,
          SwaggerUIBundle.SwaggerUIStandalonePreset
        ],
        layout: "BaseLayout",
        deepLinking: true,
        showExtensions: true,
        showCommonExtensions: true
      })
    }
  </script>
</body>
</html>

4. Postman Collection

{
  "info": {
    "name": "User Management API",
    "description": "API for managing users",
    "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json"
  },
  "auth": {
    "type": "bearer",
    "bearer": [{
      "key": "token",
      "value": "{{jwt_token}}",
      "type": "string"
    }]
  },
  "variable": [{
    "key": "base_url",
    "value": "https://api.example.com/v1"
  }],
  "item": [
    {
      "name": "Users",
      "item": [
        {
          "name": "Get All Users",
          "request": {
            "method": "GET",
            "header": [],
            "url": {
              "raw": "{{base_url}}/users?page=1&limit=20",
              "host": ["{{base_url}}"],
              "path": ["users"],
              "query": [
                {"key": "page", "value": "1"},
                {"key": "limit", "value": "20"}
              ]
            }
          }
        },
        {
          "name": "Create User",
          "request": {
            "method": "POST",
            "header": [
              {
                "key": "Content-Type",
                "value": "application/json"
              }
            ],
            "body": {
              "mode": "raw",
              "raw": "{\n  \"name\": \"John Doe\",\n  \"email\": \"john@example.com\",\n  \"password\": \"SecurePass123!\"\n}"
            },
            "url": {
              "raw": "{{base_url}}/users",
              "host": ["{{base_url}}"],
              "path": ["users"]
            }
          }
        }
      ]
    }
  ]
}

コード例生成

JavaScript/Node.js

// Get all users
const response = await fetch('https://api.example.com/v1/users?page=1&limit=20', {
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN'
  }
});
const data = await response.json();

// Create user
const newUser = await fetch('https://api.example.com/v1/users', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: 'John Doe',
    email: 'john@example.com',
    password: 'SecurePass123!'
  })
});

Python

import requests

# Get all users
headers = {'Authorization': 'Bearer YOUR_TOKEN'}
response = requests.get(
    'https://api.example.com/v1/users',
    params={'page': 1, 'limit': 20},
    headers=headers
)
users = response.json()

# Create user
new_user_data = {
    'name': 'John Doe',
    'email': 'john@example.com',
    'password': 'SecurePass123!'
}
response = requests.post(
    'https://api.example.com/v1/users',
    json=new_user_data,
    headers=headers
)

cURL

# Get all users
curl -X GET "https://api.example.com/v1/users?page=1&limit=20" \
  -H "Authorization: Bearer YOUR_TOKEN"

# Create user
curl -X POST "https://api.example.com/v1/users" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"John Doe","email":"john@example.com","password":"SecurePass123!"}'

GraphQL ドキュメント

"""
User type representing a user in the system
"""
type User {
  """Unique identifier"""
  id: ID!

  """User's full name"""
  name: String!

  """User's email address"""
  email: String!

  """Account creation timestamp"""
  createdAt: DateTime!

  """Last update timestamp"""
  updatedAt: DateTime!
}

type Query {
  """
  Get all users with pagination

  Arguments:
  - page: Page number (default: 1)
  - limit: Items per page (default: 20, max: 100)
  """
  users(page: Int = 1, limit: Int = 20): UserConnection!

  """
  Get a specific user by ID

  Returns null if user doesn't exist
  """
  user(id: ID!): User
}

type Mutation {
  """
  Create a new user

  Errors:
  - EMAIL_EXISTS: Email already registered
  - INVALID_INPUT: Validation failed
  """
  createUser(input: CreateUserInput!): User!

  """Update existing user"""
  updateUser(id: ID!, input: UpdateUserInput!): User!

  """Delete user"""
  deleteUser(id: ID!): Boolean!
}

input CreateUserInput {
  """User's full name (2-100 chars)"""
  name: String!

  """Valid email address"""
  email: String!

  """Password (min 8 chars)"""
  password: String!
}

type UserConnection {
  edges: [UserEdge!]!
  pageInfo: PageInfo!
  totalCount: Int!
}

ベストプラクティス

1. 詳細な説明

• エンドポイントの目的を明確に記述
• パラメータの意味と制約を説明
• 典型的な使用例を提供

2. リアルな例

• 実際のデータに近い例を使用
• 成功とエラーの両方のケースを含める
• エッジケースも文書化

3. バージョニング

• APIバージョンを明記
• 変更履歴を記録
• 非推奨機能の移行ガイド

4. セキュリティ

• 認証方法を明確に説明
• 権限要件を文書化
• セキュリティのベストプラクティスを提供

カスタマイズ

以下の要件でAPIドキュメントを生成：

- 出力形式: OpenAPI 3.0 + Markdown
- 認証: OAuth 2.0
- コード例言語: JavaScript, Python, Go
- エラーコード: 完全なリファレンス
- レート制限: 詳細情報を含める
- バージョン: v2.0

バージョン情報

• スキルバージョン: 1.0.0
• 最終更新: 2025-01-22

使用例:

このExpressルーターのAPIドキュメントを生成：

router.get('/api/products', async (req, res) => {
  const { category, minPrice, maxPrice } = req.query;
  const products = await Product.find({ category, price: { $gte: minPrice, $lte: maxPrice } });
  res.json(products);
});

形式: OpenAPI 3.0 + Markdown
コード例: JavaScript, Python

完全なAPIドキュメントが生成されます！