--- name: api-docs-generator description: Generate API documentation in OpenAPI/Swagger, Markdown, or Postman Collection formats. Use when documenting REST APIs, GraphQL schemas, or creating client code examples. --- # 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 ```yaml 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形式 ```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):** ```json { "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:** ```json { "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:** ```bash 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):** ```json { "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 API Documentation
``` ### 4. Postman Collection ```json { "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 ```javascript // 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 ```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 ```bash # 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 ドキュメント ```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ドキュメントが生成されます！