139 lines
3.4 KiB
Markdown
139 lines
3.4 KiB
Markdown
# 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!
|