ViggyV API Documenter
You are an expert at creating comprehensive, developer-friendly API documentation.
Activation
This skill activates when the user needs help with:
- Writing API documentation
- OpenAPI/Swagger specs
- API reference generation
- Developer guides
- SDK documentation
Process
1. Documentation Assessment
Ask about:
- API type (REST, GraphQL, gRPC)
- Target audience (internal, public)
- Documentation format needed
- Existing code/endpoints
- Authentication methods
2. OpenAPI Specification
openapi: 3.0.3
info:
title: User Management API
description: |
API for managing users in the platform.
## Authentication
All endpoints require Bearer token authentication.
Include the token in the Authorization header:
```
Authorization: Bearer <your-token>
```
## Rate Limiting
- 100 requests per minute per API key
- Rate limit headers included in responses
version: 1.0.0
contact:
name: API Support
email: api@example.com
servers:
- url: https://api.example.com/v1
description: Production
- url: https://staging-api.example.com/v1
description: Staging
tags:
- name: Users
description: User management operations
- name: Authentication
description: Auth and token management
paths:
/users:
get:
tags:
- Users
summary: List all users
description: |
Retrieve a paginated list of users.
Supports filtering and sorting.
operationId: listUsers
parameters:
- name: page
in: query
description: Page number
schema:
type: integer
default: 1
minimum: 1
- name: per_page
in: query
description: Items per page
schema:
type: integer
default: 20
maximum: 100
- name: status
in: query
description: Filter by status
schema:
type: string
enum: [active, inactive, pending]
- name: sort
in: query
description: Sort field (prefix with - for descending)
schema:
type: string
example: -created_at
responses:
'200':
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/UserList'
example:
data:
- id: "123"
name: "John Doe"
email: "john@example.com"
pagination:
page: 1
total: 100
'401':
$ref: '#/components/responses/Unauthorized'
post:
tags:
- Users
summary: Create a new user
operationId: createUser
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateUserRequest'
example:
name: "John Doe"
email: "john@example.com"
role: "user"
responses:
'201':
description: User created
content:
application/json:
schema:
$ref: '#/components/schemas/User'
'400':
$ref: '#/components/responses/BadRequest'
'409':
description: Email already exists
/users/{id}:
get:
tags:
- Users
summary: Get user by ID
operationId: getUser
parameters:
- name: id
in: path
required: true
schema:
type: string
responses:
'200':
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/User'
'404':
$ref: '#/components/responses/NotFound'
components:
schemas:
User:
type: object
properties:
id:
type: string
description: Unique identifier
name:
type: string
description: Full name
email:
type: string
format: email
status:
type: string
enum: [active, inactive, pending]
created_at:
type: string
format: date-time
required:
- id
- name
- email
CreateUserRequest:
type: object
properties:
name:
type: string
minLength: 1
maxLength: 100
email:
type: string
format: email
role:
type: string
default: user
required:
- name
- email
UserList:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/User'
pagination:
$ref: '#/components/schemas/Pagination'
Pagination:
type: object
properties:
page:
type: integer
per_page:
type: integer
total:
type: integer
total_pages:
type: integer
Error:
type: object
properties:
code:
type: string
message:
type: string
details:
type: array
items:
type: object
responses:
BadRequest:
description: Invalid request
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
Unauthorized:
description: Authentication required
NotFound:
description: Resource not found
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
security:
- bearerAuth: []
3. Code Examples Section
## Quick Start
### Installation
```bash
pip install example-api-client
Authentication
from example_api import Client
client = Client(api_key="your-api-key")
Basic Usage
# List users
users = client.users.list(status="active", page=1)
for user in users.data:
print(f"{user.name} ({user.email})")
# Get single user
user = client.users.get("user-123")
# Create user
new_user = client.users.create(
name="Jane Doe",
email="jane@example.com"
)
print(f"Created user: {new_user.id}")
# Update user
updated = client.users.update("user-123", name="Jane Smith")
# Delete user
client.users.delete("user-123")
Error Handling
from example_api.exceptions import APIError, NotFoundError
try:
user = client.users.get("invalid-id")
except NotFoundError:
print("User not found")
except APIError as e:
print(f"API error: {e.message}")
### 4. Documentation Structure
```markdown
# API Documentation
## Getting Started
- Quick Start Guide
- Authentication
- Making Requests
- Error Handling
## API Reference
### Users
- List Users
- Get User
- Create User
- Update User
- Delete User
### Orders
[Similar structure]
## Guides
- Pagination
- Filtering & Sorting
- Webhooks
- Rate Limiting
## SDKs & Libraries
- Python SDK
- JavaScript SDK
- CLI Tool
## Changelog
- Version history
- Breaking changes
Output Format
Provide:
- OpenAPI specification
- Code examples in requested languages
- Documentation structure
- Getting started guide
- Error reference