ayrisdev/app-store-optimization
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Add files via upload

Browse Source
This commit is contained in:
Mohammad Faiz
2026-01-22 16:46:43 +05:30
committed by GitHub
parent 518edc9a3c
commit 13bdb4970c
2 changed files with 622 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

138
skills/api-documentation-generator/README.md Normal file
View File

@@ -0,0 +1,138 @@
# API Documentation Generator Skill
Generate comprehensive, developer-friendly API documentation automatically from your codebase.
## What This Skill Does
This skill helps you create professional API documentation that includes:
- Endpoint descriptions with full details
- Request/response examples in multiple languages
- Authentication and authorization guides
- Error handling documentation
- Interactive examples and collections
## Quick Start
```
@api-documentation-generator Document my REST API endpoints
```
The AI will:
1. Analyze your API structure
2. Generate documentation for each endpoint
3. Include code examples in multiple languages
4. Document authentication and errors
5. Provide best practices and guidelines
## Use Cases
### 1. New API Documentation
Starting from scratch with a new API:
```
@api-documentation-generator I have a new REST API for user management.
Help me create complete documentation.
```
### 2. Update Existing Docs
Keeping documentation in sync:
```
@api-documentation-generator I added new endpoints for payments.
Update the API documentation.
```
### 3. Generate OpenAPI Spec
Creating machine-readable specifications:
```
@api-documentation-generator Generate an OpenAPI 3.0 specification
for my API endpoints.
```
### 4. Create Postman Collection
Making it easy to test:
```
@api-documentation-generator Create a Postman collection for all
my API endpoints.
```
## What You'll Get
### For Each Endpoint
- HTTP method and URL
- Description and purpose
- Authentication requirements
- Request parameters (path, query, body)
- Response formats (success and errors)
- Code examples (cURL, JavaScript, Python, etc.)
### Additional Documentation
- Getting started guide
- Authentication setup
- Error code reference
- Rate limiting details
- Best practices
- Common use cases
## Examples
### REST API
```
@api-documentation-generator Document this Express.js route:
app.post('/api/users', async (req, res) => {
const { email, password, name } = req.body;
// ... implementation
});
```
### GraphQL API
```
@api-documentation-generator Document this GraphQL schema:
type Query {
user(id: ID!): User
users(limit: Int, offset: Int): [User!]!
}
```
### WebSocket API
```
@api-documentation-generator Document this WebSocket event:
socket.on('message:send', (data) => {
// ... implementation
});
```
## Best Practices
1. **Keep It Updated** - Regenerate docs when API changes
2. **Test Examples** - Ensure all code examples work
3. **Be Comprehensive** - Document all endpoints, not just the happy path
4. **Use Standards** - Follow OpenAPI/Swagger specifications
5. **Provide Context** - Explain why, not just what
## Tips
- Provide your API code or route definitions for best results
- Mention your tech stack (Express, FastAPI, GraphQL, etc.)
- Specify which programming languages you want examples in
- Include any existing documentation to maintain consistency
## Related Skills
- `@doc-coauthoring` - Collaborative documentation
- `@copywriting` - Clear, user-friendly writing
- `@test-driven-development` - Ensure API behavior matches docs
## Output Formats
This skill can generate documentation in:
- Markdown (for GitHub, GitBook, etc.)
- OpenAPI/Swagger YAML
- Postman Collection JSON
- HTML (for static sites)
- ReDoc/Swagger UI compatible formats
---
**Pro Tip:** Use this skill early in development to establish documentation patterns, then keep it updated as your API evolves!

484
skills/api-documentation-generator/SKILL.md Normal file
View File

@@ -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!