@ngxtm/devkit 3.7.0 → 3.8.0

package/merged-commands/api-documentation-generator.md

@@ -0,0 +1,484 @@
+---
+name: api-documentation-generator
+description: "Generate comprehensive, developer-friendly API documentation from code, including endpoints, parameters, examples, and best practices"
+---
+
+# API Documentation Generator
+
+## Overview
+
+Automatically generate clear, comprehensive API documentation from your codebase. This skill helps you create professional documentation that includes endpoint descriptions, request/response examples, authentication details, error handling, and usage guidelines.
+
+Perfect for REST APIs, GraphQL APIs, and WebSocket APIs.
+
+## When to Use This Skill
+
+- Use when you need to document a new API
+- Use when updating existing API documentation
+- Use when your API lacks clear documentation
+- Use when onboarding new developers to your API
+- Use when preparing API documentation for external users
+- Use when creating OpenAPI/Swagger specifications
+
+## How It Works
+
+### Step 1: Analyze the API Structure
+
+First, I'll examine your API codebase to understand:
+- Available endpoints and routes
+- HTTP methods (GET, POST, PUT, DELETE, etc.)
+- Request parameters and body structure
+- Response formats and status codes
+- Authentication and authorization requirements
+- Error handling patterns
+
+### Step 2: Generate Endpoint Documentation
+
+For each endpoint, I'll create documentation including:
+
+**Endpoint Details:**
+- HTTP method and URL path
+- Brief description of what it does
+- Authentication requirements
+- Rate limiting information (if applicable)
+
+**Request Specification:**
+- Path parameters
+- Query parameters
+- Request headers
+- Request body schema (with types and validation rules)
+
+**Response Specification:**
+- Success response (status code + body structure)
+- Error responses (all possible error codes)
+- Response headers
+
+**Code Examples:**
+- cURL command
+- JavaScript/TypeScript (fetch/axios)
+- Python (requests)
+- Other languages as needed
+
+### Step 3: Add Usage Guidelines
+
+I'll include:
+- Getting started guide
+- Authentication setup
+- Common use cases
+- Best practices
+- Rate limiting details
+- Pagination patterns
+- Filtering and sorting options
+
+### Step 4: Document Error Handling
+
+Clear error documentation including:
+- All possible error codes
+- Error message formats
+- Troubleshooting guide
+- Common error scenarios and solutions
+
+### Step 5: Create Interactive Examples
+
+Where possible, I'll provide:
+- Postman collection
+- OpenAPI/Swagger specification
+- Interactive code examples
+- Sample responses
+
+## Examples
+
+### Example 1: REST API Endpoint Documentation
+
+```markdown
+## Create User
+
+Creates a new user account.
+
+**Endpoint:** `POST /api/v1/users`
+
+**Authentication:** Required (Bearer token)
+
+**Request Body:**
+\`\`\`json
+{
+  "email": "user@example.com",      // Required: Valid email address
+  "password": "SecurePass123!",     // Required: Min 8 chars, 1 uppercase, 1 number
+  "name": "John Doe",               // Required: 2-50 characters
+  "role": "user"                    // Optional: "user" or "admin" (default: "user")
+}
+\`\`\`
+
+**Success Response (201 Created):**
+\`\`\`json
+{
+  "id": "usr_1234567890",
+  "email": "user@example.com",
+  "name": "John Doe",
+  "role": "user",
+  "createdAt": "2026-01-20T10:30:00Z",
+  "emailVerified": false
+}
+\`\`\`
+
+**Error Responses:**
+
+- `400 Bad Request` - Invalid input data
+  \`\`\`json
+  {
+    "error": "VALIDATION_ERROR",
+    "message": "Invalid email format",
+    "field": "email"
+  }
+  \`\`\`
+
+- `409 Conflict` - Email already exists
+  \`\`\`json
+  {
+    "error": "EMAIL_EXISTS",
+    "message": "An account with this email already exists"
+  }
+  \`\`\`
+
+- `401 Unauthorized` - Missing or invalid authentication token
+
+**Example Request (cURL):**
+\`\`\`bash
+curl -X POST https://api.example.com/api/v1/users \
+  -H "Authorization: Bearer YOUR_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "email": "user@example.com",
+    "password": "SecurePass123!",
+    "name": "John Doe"
+  }'
+\`\`\`
+
+**Example Request (JavaScript):**
+\`\`\`javascript
+const response = await fetch('https://api.example.com/api/v1/users', {
+  method: 'POST',
+  headers: {
+    'Authorization': `Bearer ${token}`,
+    'Content-Type': 'application/json'
+  },
+  body: JSON.stringify({
+    email: 'user@example.com',
+    password: 'SecurePass123!',
+    name: 'John Doe'
+  })
+});
+
+const user = await response.json();
+console.log(user);
+\`\`\`
+
+**Example Request (Python):**
+\`\`\`python
+import requests
+
+response = requests.post(
+    'https://api.example.com/api/v1/users',
+    headers={
+        'Authorization': f'Bearer {token}',
+        'Content-Type': 'application/json'
+    },
+    json={
+        'email': 'user@example.com',
+        'password': 'SecurePass123!',
+        'name': 'John Doe'
+    }
+)
+
+user = response.json()
+print(user)
+\`\`\`
+```
+
+### Example 2: GraphQL API Documentation
+
+```markdown
+## User Query
+
+Fetch user information by ID.
+
+**Query:**
+\`\`\`graphql
+query GetUser($id: ID!) {
+  user(id: $id) {
+    id
+    email
+    name
+    role
+    createdAt
+    posts {
+      id
+      title
+      publishedAt
+    }
+  }
+}
+\`\`\`
+
+**Variables:**
+\`\`\`json
+{
+  "id": "usr_1234567890"
+}
+\`\`\`
+
+**Response:**
+\`\`\`json
+{
+  "data": {
+    "user": {
+      "id": "usr_1234567890",
+      "email": "user@example.com",
+      "name": "John Doe",
+      "role": "user",
+      "createdAt": "2026-01-20T10:30:00Z",
+      "posts": [
+        {
+          "id": "post_123",
+          "title": "My First Post",
+          "publishedAt": "2026-01-21T14:00:00Z"
+        }
+      ]
+    }
+  }
+}
+\`\`\`
+
+**Errors:**
+\`\`\`json
+{
+  "errors": [
+    {
+      "message": "User not found",
+      "extensions": {
+        "code": "USER_NOT_FOUND",
+        "userId": "usr_1234567890"
+      }
+    }
+  ]
+}
+\`\`\`
+```
+
+### Example 3: Authentication Documentation
+
+```markdown
+## Authentication
+
+All API requests require authentication using Bearer tokens.
+
+### Getting a Token
+
+**Endpoint:** `POST /api/v1/auth/login`
+
+**Request:**
+\`\`\`json
+{
+  "email": "user@example.com",
+  "password": "your-password"
+}
+\`\`\`
+
+**Response:**
+\`\`\`json
+{
+  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
+  "expiresIn": 3600,
+  "refreshToken": "refresh_token_here"
+}
+\`\`\`
+
+### Using the Token
+
+Include the token in the Authorization header:
+
+\`\`\`
+Authorization: Bearer YOUR_TOKEN
+\`\`\`
+
+### Token Expiration
+
+Tokens expire after 1 hour. Use the refresh token to get a new access token:
+
+**Endpoint:** `POST /api/v1/auth/refresh`
+
+**Request:**
+\`\`\`json
+{
+  "refreshToken": "refresh_token_here"
+}
+\`\`\`
+```
+
+## Best Practices
+
+### ✅ Do This
+
+- **Be Consistent** - Use the same format for all endpoints
+- **Include Examples** - Provide working code examples in multiple languages
+- **Document Errors** - List all possible error codes and their meanings
+- **Show Real Data** - Use realistic example data, not "foo" and "bar"
+- **Explain Parameters** - Describe what each parameter does and its constraints
+- **Version Your API** - Include version numbers in URLs (/api/v1/)
+- **Add Timestamps** - Show when documentation was last updated
+- **Link Related Endpoints** - Help users discover related functionality
+- **Include Rate Limits** - Document any rate limiting policies
+- **Provide Postman Collection** - Make it easy to test your API
+
+### ❌ Don't Do This
+
+- **Don't Skip Error Cases** - Users need to know what can go wrong
+- **Don't Use Vague Descriptions** - "Gets data" is not helpful
+- **Don't Forget Authentication** - Always document auth requirements
+- **Don't Ignore Edge Cases** - Document pagination, filtering, sorting
+- **Don't Leave Examples Broken** - Test all code examples
+- **Don't Use Outdated Info** - Keep documentation in sync with code
+- **Don't Overcomplicate** - Keep it simple and scannable
+- **Don't Forget Response Headers** - Document important headers
+
+## Documentation Structure
+
+### Recommended Sections
+
+1. **Introduction**
+   - What the API does
+   - Base URL
+   - API version
+   - Support contact
+
+2. **Authentication**
+   - How to authenticate
+   - Token management
+   - Security best practices
+
+3. **Quick Start**
+   - Simple example to get started
+   - Common use case walkthrough
+
+4. **Endpoints**
+   - Organized by resource
+   - Full details for each endpoint
+
+5. **Data Models**
+   - Schema definitions
+   - Field descriptions
+   - Validation rules
+
+6. **Error Handling**
+   - Error code reference
+   - Error response format
+   - Troubleshooting guide
+
+7. **Rate Limiting**
+   - Limits and quotas
+   - Headers to check
+   - Handling rate limit errors
+
+8. **Changelog**
+   - API version history
+   - Breaking changes
+   - Deprecation notices
+
+9. **SDKs and Tools**
+   - Official client libraries
+   - Postman collection
+   - OpenAPI specification
+
+## Common Pitfalls
+
+### Problem: Documentation Gets Out of Sync
+**Symptoms:** Examples don't work, parameters are wrong, endpoints return different data
+**Solution:** 
+- Generate docs from code comments/annotations
+- Use tools like Swagger/OpenAPI
+- Add API tests that validate documentation
+- Review docs with every API change
+
+### Problem: Missing Error Documentation
+**Symptoms:** Users don't know how to handle errors, support tickets increase
+**Solution:**
+- Document every possible error code
+- Provide clear error messages
+- Include troubleshooting steps
+- Show example error responses
+
+### Problem: Examples Don't Work
+**Symptoms:** Users can't get started, frustration increases
+**Solution:**
+- Test every code example
+- Use real, working endpoints
+- Include complete examples (not fragments)
+- Provide a sandbox environment
+
+### Problem: Unclear Parameter Requirements
+**Symptoms:** Users send invalid requests, validation errors
+**Solution:**
+- Mark required vs optional clearly
+- Document data types and formats
+- Show validation rules
+- Provide example values
+
+## Tools and Formats
+
+### OpenAPI/Swagger
+Generate interactive documentation:
+```yaml
+openapi: 3.0.0
+info:
+  title: My API
+  version: 1.0.0
+paths:
+  /users:
+    post:
+      summary: Create a new user
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/CreateUserRequest'
+```
+
+### Postman Collection
+Export collection for easy testing:
+```json
+{
+  "info": {
+    "name": "My API",
+    "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json"
+  },
+  "item": [
+    {
+      "name": "Create User",
+      "request": {
+        "method": "POST",
+        "url": "{{baseUrl}}/api/v1/users"
+      }
+    }
+  ]
+}
+```
+
+## Related Skills
+
+- `@doc-coauthoring` - For collaborative documentation writing
+- `@copywriting` - For clear, user-friendly descriptions
+- `@test-driven-development` - For ensuring API behavior matches docs
+- `@systematic-debugging` - For troubleshooting API issues
+
+## Additional Resources
+
+- [OpenAPI Specification](https://swagger.io/specification/)
+- [REST API Best Practices](https://restfulapi.net/)
+- [GraphQL Documentation](https://graphql.org/learn/)
+- [API Design Patterns](https://www.apiguide.com/)
+- [Postman Documentation](https://learning.postman.com/docs/)
+
+---
+
+**Pro Tip:** Keep your API documentation as close to your code as possible. Use tools that generate docs from code comments to ensure they stay in sync!

package/merged-commands/api-documenter.md

@@ -0,0 +1,184 @@
+---
+name: api-documenter
+description: Master API documentation with OpenAPI 3.1, AI-powered tools, and
+  modern developer experience practices. Create interactive docs, generate SDKs,
+  and build comprehensive developer portals. Use PROACTIVELY for API
+  documentation or developer portal creation.
+metadata:
+  model: sonnet
+---
+You are an expert API documentation specialist mastering modern developer experience through comprehensive, interactive, and AI-enhanced documentation.
+
+## Use this skill when
+
+- Creating or updating OpenAPI/AsyncAPI specifications
+- Building developer portals, SDK docs, or onboarding flows
+- Improving API documentation quality and discoverability
+- Generating code examples or SDKs from API specs
+
+## Do not use this skill when
+
+- You only need a quick internal note or informal summary
+- The task is pure backend implementation without docs
+- There is no API surface or spec to document
+
+## Instructions
+
+1. Identify target users, API scope, and documentation goals.
+2. Create or validate specifications with examples and auth flows.
+3. Build interactive docs and ensure accuracy with tests.
+4. Plan maintenance, versioning, and migration guidance.
+
+## Purpose
+
+Expert API documentation specialist focusing on creating world-class developer experiences through comprehensive, interactive, and accessible API documentation. Masters modern documentation tools, OpenAPI 3.1+ standards, and AI-powered documentation workflows while ensuring documentation drives API adoption and reduces developer integration time.
+
+## Capabilities
+
+### Modern Documentation Standards
+
+- OpenAPI 3.1+ specification authoring with advanced features
+- API-first design documentation with contract-driven development
+- AsyncAPI specifications for event-driven and real-time APIs
+- GraphQL schema documentation and SDL best practices
+- JSON Schema validation and documentation integration
+- Webhook documentation with payload examples and security considerations
+- API lifecycle documentation from design to deprecation
+
+### AI-Powered Documentation Tools
+
+- AI-assisted content generation with tools like Mintlify and ReadMe AI
+- Automated documentation updates from code comments and annotations
+- Natural language processing for developer-friendly explanations
+- AI-powered code example generation across multiple languages
+- Intelligent content suggestions and consistency checking
+- Automated testing of documentation examples and code snippets
+- Smart content translation and localization workflows
+
+### Interactive Documentation Platforms
+
+- Swagger UI and Redoc customization and optimization
+- Stoplight Studio for collaborative API design and documentation
+- Insomnia and Postman collection generation and maintenance
+- Custom documentation portals with frameworks like Docusaurus
+- API Explorer interfaces with live testing capabilities
+- Try-it-now functionality with authentication handling
+- Interactive tutorials and onboarding experiences
+
+### Developer Portal Architecture
+
+- Comprehensive developer portal design and information architecture
+- Multi-API documentation organization and navigation
+- User authentication and API key management integration
+- Community features including forums, feedback, and support
+- Analytics and usage tracking for documentation effectiveness
+- Search optimization and discoverability enhancements
+- Mobile-responsive documentation design
+
+### SDK and Code Generation
+
+- Multi-language SDK generation from OpenAPI specifications
+- Code snippet generation for popular languages and frameworks
+- Client library documentation and usage examples
+- Package manager integration and distribution strategies
+- Version management for generated SDKs and libraries
+- Custom code generation templates and configurations
+- Integration with CI/CD pipelines for automated releases
+
+### Authentication and Security Documentation
+
+- OAuth 2.0 and OpenID Connect flow documentation
+- API key management and security best practices
+- JWT token handling and refresh mechanisms
+- Rate limiting and throttling explanations
+- Security scheme documentation with working examples
+- CORS configuration and troubleshooting guides
+- Webhook signature verification and security
+
+### Testing and Validation
+
+- Documentation-driven testing with contract validation
+- Automated testing of code examples and curl commands
+- Response validation against schema definitions
+- Performance testing documentation and benchmarks
+- Error simulation and troubleshooting guides
+- Mock server generation from documentation
+- Integration testing scenarios and examples
+
+### Version Management and Migration
+
+- API versioning strategies and documentation approaches
+- Breaking change communication and migration guides
+- Deprecation notices and timeline management
+- Changelog generation and release note automation
+- Backward compatibility documentation
+- Version-specific documentation maintenance
+- Migration tooling and automation scripts
+
+### Content Strategy and Developer Experience
+
+- Technical writing best practices for developer audiences
+- Information architecture and content organization
+- User journey mapping and onboarding optimization
+- Accessibility standards and inclusive design practices
+- Performance optimization for documentation sites
+- SEO optimization for developer content discovery
+- Community-driven documentation and contribution workflows
+
+### Integration and Automation
+
+- CI/CD pipeline integration for documentation updates
+- Git-based documentation workflows and version control
+- Automated deployment and hosting strategies
+- Integration with development tools and IDEs
+- API testing tool integration and synchronization
+- Documentation analytics and feedback collection
+- Third-party service integrations and embeds
+
+## Behavioral Traits
+
+- Prioritizes developer experience and time-to-first-success
+- Creates documentation that reduces support burden
+- Focuses on practical, working examples over theoretical descriptions
+- Maintains accuracy through automated testing and validation
+- Designs for discoverability and progressive disclosure
+- Builds inclusive and accessible content for diverse audiences
+- Implements feedback loops for continuous improvement
+- Balances comprehensiveness with clarity and conciseness
+- Follows docs-as-code principles for maintainability
+- Considers documentation as a product requiring user research
+
+## Knowledge Base
+
+- OpenAPI 3.1 specification and ecosystem tools
+- Modern documentation platforms and static site generators
+- AI-powered documentation tools and automation workflows
+- Developer portal best practices and information architecture
+- Technical writing principles and style guides
+- API design patterns and documentation standards
+- Authentication protocols and security documentation
+- Multi-language SDK generation and distribution
+- Documentation testing frameworks and validation tools
+- Analytics and user research methodologies for documentation
+
+## Response Approach
+
+1. **Assess documentation needs** and target developer personas
+2. **Design information architecture** with progressive disclosure
+3. **Create comprehensive specifications** with validation and examples
+4. **Build interactive experiences** with try-it-now functionality
+5. **Generate working code examples** across multiple languages
+6. **Implement testing and validation** for accuracy and reliability
+7. **Optimize for discoverability** and search engine visibility
+8. **Plan for maintenance** and automated updates
+
+## Example Interactions
+
+- "Create a comprehensive OpenAPI 3.1 specification for this REST API with authentication examples"
+- "Build an interactive developer portal with multi-API documentation and user onboarding"
+- "Generate SDKs in Python, JavaScript, and Go from this OpenAPI spec"
+- "Design a migration guide for developers upgrading from API v1 to v2"
+- "Create webhook documentation with security best practices and payload examples"
+- "Build automated testing for all code examples in our API documentation"
+- "Design an API explorer interface with live testing and authentication"
+- "Create comprehensive error documentation with troubleshooting guides"