From f85f1c70de7d4913c22d74aef2bbe620104b2809 Mon Sep 17 00:00:00 2001 From: Zhongwei Li Date: Sat, 29 Nov 2025 18:12:37 +0800 Subject: [PATCH] Initial commit --- .claude-plugin/plugin.json | 12 +++ README.md | 3 + commands/generate-api-docs.md | 152 ++++++++++++++++++++++++++++++++++ plugin.lock.json | 45 ++++++++++ 4 files changed, 212 insertions(+) create mode 100644 .claude-plugin/plugin.json create mode 100644 README.md create mode 100644 commands/generate-api-docs.md create mode 100644 plugin.lock.json diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json new file mode 100644 index 0000000..b757380 --- /dev/null +++ b/.claude-plugin/plugin.json @@ -0,0 +1,12 @@ +{ + "name": "api-docs-generator", + "description": "Generate API documentation for endpoints", + "version": "1.0.0", + "author": { + "name": "ClaudeForge Community", + "url": "https://github.com/claudeforge/marketplace" + }, + "commands": [ + "./commands" + ] +} \ No newline at end of file diff --git a/README.md b/README.md new file mode 100644 index 0000000..0f0238a --- /dev/null +++ b/README.md @@ -0,0 +1,3 @@ +# api-docs-generator + +Generate API documentation for endpoints diff --git a/commands/generate-api-docs.md b/commands/generate-api-docs.md new file mode 100644 index 0000000..cab3ba2 --- /dev/null +++ b/commands/generate-api-docs.md @@ -0,0 +1,152 @@ +--- +allowed-tools: Bash, Read, Write, Edit, Grep, Glob +description: ClaudeForge API documentation generator for creating comprehensive, interactive API docs with OpenAPI/Swagger specifications. +--- + +# ClaudeForge API Documentation Generator + +ClaudeForge intelligent API documentation system that automatically generates comprehensive, interactive API documentation from source code analysis with OpenAPI 3.0 specification support. + +## Purpose + +Transform API documentation from manual effort to intelligent automation that ensures accuracy, consistency, and maintainability across RESTful APIs, GraphQL schemas, and microservice architectures. + +## Features + +- **Automatic Discovery**: Scan codebase to identify API endpoints, routes, and controllers +- **OpenAPI Specification**: Generate OpenAPI 3.0/Swagger 2.0 compliant documentation +- **Interactive Documentation**: Create Swagger UI and ReDoc for interactive API exploration +- **Type Safety**: Generate TypeScript definitions and validation schemas +- **Authentication Support**: Document OAuth2, JWT, API key, and custom authentication methods +- **Request/Response Examples**: Generate realistic examples for all endpoints +- **Version Management**: Handle API versioning and deprecation documentation +- **Multi-Format Export**: Export to HTML, PDF, Markdown, and Postman collections + +## Usage + +```bash +/generate-api-docs [options] [target] +``` + +Target: $ARGUMENTS (if specified, otherwise analyze current project) + +### Command Options + +**Basic Documentation Generation:** +```bash +/generate-api-docs --format=swagger --output=./docs +``` +Generates comprehensive API documentation including: +- OpenAPI 3.0 specification file +- Interactive Swagger UI +- ReDoc documentation +- TypeScript client definitions +- Postman collection for testing + +**Advanced Options:** +```bash +/generate-api-docs --format=openapi --version=3.0 --auth=JWT --examples=true +``` +Creates enhanced documentation with: +- Authentication flow documentation +- Request/response examples with real data +- Error handling and status code documentation +- Rate limiting and usage policies +- SDK generation support + +### Context Analysis + +**API Route Discovery:** +- Use Glob to find API routes: Search for files in `*/routes/*` and `*/api/*` directories with `.js` extension +- Current API files: @$ARGUMENTS +- Framework detection: Express.js, Fastify, Koa, NestJS, etc. +- Use Glob to find database models: Search in `*/models/*` and `*/schemas/*` directories + +## Documentation Standards + +### OpenAPI 3.0 Specification +- **Info Section**: Complete API metadata, contact information, license +- **Servers**: Multiple environment URLs (development, staging, production) +- **Paths**: All endpoints with proper HTTP methods and parameters +- **Components**: Reusable schemas, responses, parameters, examples +- **Security**: Authentication and authorization schemes +- **Tags**: Logical grouping of endpoints for better organization + +### Quality Assurance +- **Completeness**: All endpoints documented with required parameters +- **Accuracy**: Documentation matches actual implementation +- **Consistency**: Uniform formatting and style across all endpoints +- **Usability**: Clear descriptions and practical examples +- **Maintainability**: Easy to update as API evolves + +### Documentation Sections + +**1. API Overview** +- Introduction and purpose +- Authentication requirements +- Rate limiting and usage policies +- Base URLs and versioning information +- Supported data formats and content types + +**2. Authentication & Authorization** +- Authentication methods (OAuth2, JWT, API Keys) +- Authorization scopes and permissions +- Token acquisition and refresh processes +- Error handling for authentication failures + +**3. Endpoints Documentation** +For each endpoint: +- HTTP method and full URL path +- Description of endpoint purpose and behavior +- Path parameters, query parameters, headers +- Request body schema with validation rules +- Response schemas for all status codes +- Error responses and troubleshooting +- Rate limits and usage constraints + +**4. Data Models** +- Complete schema definitions +- Field descriptions and validation rules +- Example values and formats +- Relationship between models +- Enum values and constraints + +**5. SDK & Integration** +- Code examples in multiple languages +- SDK installation and usage +- Webhook documentation (if applicable) +- Integration best practices +- Testing and debugging guides + +## Generated Output Files + +**OpenAPI Specification:** +- `openapi.json` - Complete OpenAPI 3.0 specification +- `openapi.yaml` - YAML format for better readability +- Validation against OpenAPI 3.0 schema + +**Interactive Documentation:** +- `swagger-ui.html` - Interactive API exploration interface +- `redoc.html` - Three-panel API documentation +- `api-reference.md` - Markdown documentation + +**Developer Resources:** +- `types.d.ts` - TypeScript type definitions +- `postman-collection.json` - Postman collection for testing +- `client-sdk.js` - Generated JavaScript client +- `examples/` - Code examples in multiple languages + +## ClaudeForge Integration + +**Repository URL:** https://github.com/claudeforge/marketplace/tree/main/plugins/api-docs-generator + +**ClaudeForge Standards:** +- Generate production-ready documentation that meets enterprise standards +- Ensure security information is accurately documented +- Provide clear, actionable examples for developers +- Maintain consistency with ClaudeForge marketplace quality standards +- Support continuous integration and automated documentation updates + +Your goal is to create comprehensive, accurate, and user-friendly API documentation that serves as the definitive reference for API consumers, ensuring seamless integration and developer experience. + +Remember: Well-documented APIs are easier to adopt, integrate, and maintain. Through ClaudeForge automated documentation generation, you create API documentation that enhances developer productivity and API adoption. \ No newline at end of file diff --git a/plugin.lock.json b/plugin.lock.json new file mode 100644 index 0000000..b3f80bf --- /dev/null +++ b/plugin.lock.json @@ -0,0 +1,45 @@ +{ + "$schema": "internal://schemas/plugin.lock.v1.json", + "pluginId": "gh:claudeforge/marketplace:plugins/commands/api-docs-generator", + "normalized": { + "repo": null, + "ref": "refs/tags/v20251128.0", + "commit": "b65f17ca5d4a713a1a46163542d9cd953e2be5f9", + "treeHash": "3d4c3938931af33ef6e1f30ed60944d880bb586ff11a79bd36bf7859e8d6616e", + "generatedAt": "2025-11-28T10:15:25.766933Z", + "toolVersion": "publish_plugins.py@0.2.0" + }, + "origin": { + "remote": "git@github.com:zhongweili/42plugin-data.git", + "branch": "master", + "commit": "aa1497ed0949fd50e99e70d6324a29c5b34f9390", + "repoRoot": "/Users/zhongweili/projects/openmind/42plugin-data" + }, + "manifest": { + "name": "api-docs-generator", + "description": "Generate API documentation for endpoints", + "version": "1.0.0" + }, + "content": { + "files": [ + { + "path": "README.md", + "sha256": "cf7bc9cfea3ff4894f2b46e0d60632631ddd04c688eddd97256c75f0169d91c2" + }, + { + "path": ".claude-plugin/plugin.json", + "sha256": "12729b71bf4d1e9c39b7ba12ca3be0e6c69cc09076cd38893b9c97ab9f2aef27" + }, + { + "path": "commands/generate-api-docs.md", + "sha256": "89ee8545a4a0a84f3b25e6402cda8ea506bf16d076ed6657958932d5b5c5229b" + } + ], + "dirSha256": "3d4c3938931af33ef6e1f30ed60944d880bb586ff11a79bd36bf7859e8d6616e" + }, + "security": { + "scannedAt": null, + "scannerVersion": null, + "flags": [] + } +} \ No newline at end of file