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 含める内容:

認証フロー
すべてのエンドポイント
データモデル
エラーコード

出力形式

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

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:

curl -X GET "https://api.example.com/v1/users?page=1&#x26;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:

Field
Type
Required
Constraints

name
string
Yes
2-100 characters

email
string
Yes
Valid email format

password
string
Yes
Min 8 chars, mixed case

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

Code
Message
Description

1001
Invalid email format
Email doesn't match required format

1002
Email already exists
Account with this email exists

1003
Password too weak
Password doesn't meet requirements

2001
User not found
User ID doesn't exist

3001
Unauthorized access
Missing or invalid authentication

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
&#x3C;!DOCTYPE html>
&#x3C;html>
&#x3C;head>
  &#x3C;title>API Documentation&#x3C;/title>
  &#x3C;link rel="stylesheet" href="https://unpkg.com/swagger-ui-dist@5/swagger-ui.css" />
&#x3C;/head>
&#x3C;body>
  &#x3C;div id="swagger-ui">&#x3C;/div>
  &#x3C;script src="https://unpkg.com/swagger-ui-dist@5/swagger-ui-bundle.js">&#x3C;/script>
  &#x3C;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
      })
    }
  &#x3C;/script>
&#x3C;/body>
&#x3C;/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&#x26;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&#x26;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&#x26;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ドキュメントが生成されます！

api-docs-generator

Safety Notice

Copy this and send it to your AI assistant to learn

User Management API Documentation

Authentication

Endpoints

Get All Users

Source Transparency

Related Skills

pptx-generator

document-summarizer

excel-processor