Update WIP.md with endpoint analysis
This commit is contained in:
root
parent
70fbc7a035
commit
104aedbcf4
487
docs/api-reference.md
Normal file
487
docs/api-reference.md
Normal file
@ -0,0 +1,487 @@
|
||||
# API Reference
|
||||
|
||||
Auto-generated API documentation.
|
||||
|
||||
Last updated: kwork-api
|
||||
|
||||
---
|
||||
|
||||
## KworkClient
|
||||
|
||||
Kwork.ru API client.
|
||||
|
||||
Usage:
|
||||
# Login with credentials
|
||||
client = await KworkClient.login("username", "password")
|
||||
|
||||
# Or restore from token
|
||||
client = KworkClient(token="your_web_auth_token")
|
||||
|
||||
# Make requests
|
||||
catalog = await client.catalog.get_list(page=1)
|
||||
|
||||
### Methods
|
||||
|
||||
#### `catalog()`
|
||||
|
||||
Catalog API.
|
||||
|
||||
#### `projects()`
|
||||
|
||||
Projects API.
|
||||
|
||||
#### `user()`
|
||||
|
||||
User API.
|
||||
|
||||
#### `reference()`
|
||||
|
||||
Reference data API.
|
||||
|
||||
#### `notifications()`
|
||||
|
||||
Notifications API.
|
||||
|
||||
#### `other()`
|
||||
|
||||
Other endpoints.
|
||||
|
||||
|
||||
---
|
||||
|
||||
## CatalogAPI
|
||||
|
||||
Catalog/Kworks API endpoints.
|
||||
|
||||
---
|
||||
|
||||
## ProjectsAPI
|
||||
|
||||
Projects (freelance orders) API endpoints.
|
||||
|
||||
---
|
||||
|
||||
## UserAPI
|
||||
|
||||
User API endpoints.
|
||||
|
||||
---
|
||||
|
||||
## ReferenceAPI
|
||||
|
||||
Reference data (cities, countries, etc.) endpoints.
|
||||
|
||||
---
|
||||
|
||||
## NotificationsAPI
|
||||
|
||||
Notifications and messages endpoints.
|
||||
|
||||
---
|
||||
|
||||
## OtherAPI
|
||||
|
||||
Other API endpoints.
|
||||
|
||||
---
|
||||
|
||||
|
||||
# Models
|
||||
|
||||
Pydantic models used in API responses.
|
||||
|
||||
## KworkUser
|
||||
|
||||
User information.
|
||||
|
||||
### Fields
|
||||
|
||||
| Field | Type | Description |
|
||||
|-------|------|-------------|
|
||||
| `id` | - | - |
|
||||
| `username` | - | - |
|
||||
| `avatar_url` | - | - |
|
||||
| `is_online` | - | - |
|
||||
| `rating` | - | - |
|
||||
|
||||
---
|
||||
|
||||
## KworkCategory
|
||||
|
||||
Category information.
|
||||
|
||||
### Fields
|
||||
|
||||
| Field | Type | Description |
|
||||
|-------|------|-------------|
|
||||
| `id` | - | - |
|
||||
| `name` | - | - |
|
||||
| `slug` | - | - |
|
||||
| `parent_id` | - | - |
|
||||
|
||||
---
|
||||
|
||||
## Kwork
|
||||
|
||||
Kwork (service) information.
|
||||
|
||||
### Fields
|
||||
|
||||
| Field | Type | Description |
|
||||
|-------|------|-------------|
|
||||
| `id` | - | - |
|
||||
| `title` | - | - |
|
||||
| `description` | - | - |
|
||||
| `price` | - | - |
|
||||
| `currency` | - | - |
|
||||
| `category_id` | - | - |
|
||||
| `seller` | - | - |
|
||||
| `images` | - | - |
|
||||
| `rating` | - | - |
|
||||
| `reviews_count` | - | - |
|
||||
| `created_at` | - | - |
|
||||
| `updated_at` | - | - |
|
||||
|
||||
---
|
||||
|
||||
## KworkDetails
|
||||
|
||||
Extended kwork details.
|
||||
|
||||
### Fields
|
||||
|
||||
| Field | Type | Description |
|
||||
|-------|------|-------------|
|
||||
| `full_description` | - | - |
|
||||
| `requirements` | - | - |
|
||||
| `delivery_time` | - | - |
|
||||
| `revisions` | - | - |
|
||||
| `features` | - | - |
|
||||
| `faq` | - | - |
|
||||
|
||||
---
|
||||
|
||||
## PaginationInfo
|
||||
|
||||
Pagination metadata.
|
||||
|
||||
### Fields
|
||||
|
||||
| Field | Type | Description |
|
||||
|-------|------|-------------|
|
||||
| `current_page` | - | - |
|
||||
| `total_pages` | - | - |
|
||||
| `total_items` | - | - |
|
||||
| `items_per_page` | - | - |
|
||||
| `has_next` | - | - |
|
||||
| `has_prev` | - | - |
|
||||
|
||||
---
|
||||
|
||||
## CatalogResponse
|
||||
|
||||
Catalog response with kworks and pagination.
|
||||
|
||||
### Fields
|
||||
|
||||
| Field | Type | Description |
|
||||
|-------|------|-------------|
|
||||
| `kworks` | - | - |
|
||||
| `pagination` | - | - |
|
||||
| `filters` | - | - |
|
||||
| `sort_options` | - | - |
|
||||
|
||||
---
|
||||
|
||||
## Project
|
||||
|
||||
Project (freelance order) information.
|
||||
|
||||
### Fields
|
||||
|
||||
| Field | Type | Description |
|
||||
|-------|------|-------------|
|
||||
| `id` | - | - |
|
||||
| `title` | - | - |
|
||||
| `description` | - | - |
|
||||
| `budget` | - | - |
|
||||
| `budget_type` | - | - |
|
||||
| `category_id` | - | - |
|
||||
| `customer` | - | - |
|
||||
| `status` | - | - |
|
||||
| `created_at` | - | - |
|
||||
| `updated_at` | - | - |
|
||||
| `bids_count` | - | - |
|
||||
| `skills` | - | - |
|
||||
|
||||
---
|
||||
|
||||
## ProjectsResponse
|
||||
|
||||
Projects list response.
|
||||
|
||||
### Fields
|
||||
|
||||
| Field | Type | Description |
|
||||
|-------|------|-------------|
|
||||
| `projects` | - | - |
|
||||
| `pagination` | - | - |
|
||||
|
||||
---
|
||||
|
||||
## Review
|
||||
|
||||
Review information.
|
||||
|
||||
### Fields
|
||||
|
||||
| Field | Type | Description |
|
||||
|-------|------|-------------|
|
||||
| `id` | - | - |
|
||||
| `rating` | - | - |
|
||||
| `comment` | - | - |
|
||||
| `author` | - | - |
|
||||
| `kwork_id` | - | - |
|
||||
| `created_at` | - | - |
|
||||
|
||||
---
|
||||
|
||||
## ReviewsResponse
|
||||
|
||||
Reviews list response.
|
||||
|
||||
### Fields
|
||||
|
||||
| Field | Type | Description |
|
||||
|-------|------|-------------|
|
||||
| `reviews` | - | - |
|
||||
| `pagination` | - | - |
|
||||
| `average_rating` | - | - |
|
||||
|
||||
---
|
||||
|
||||
## Notification
|
||||
|
||||
Notification information.
|
||||
|
||||
### Fields
|
||||
|
||||
| Field | Type | Description |
|
||||
|-------|------|-------------|
|
||||
| `id` | - | - |
|
||||
| `type` | - | - |
|
||||
| `title` | - | - |
|
||||
| `message` | - | - |
|
||||
| `is_read` | - | - |
|
||||
| `created_at` | - | - |
|
||||
| `link` | - | - |
|
||||
|
||||
---
|
||||
|
||||
## NotificationsResponse
|
||||
|
||||
Notifications list response.
|
||||
|
||||
### Fields
|
||||
|
||||
| Field | Type | Description |
|
||||
|-------|------|-------------|
|
||||
| `notifications` | - | - |
|
||||
| `unread_count` | - | - |
|
||||
|
||||
---
|
||||
|
||||
## Dialog
|
||||
|
||||
Dialog (chat) information.
|
||||
|
||||
### Fields
|
||||
|
||||
| Field | Type | Description |
|
||||
|-------|------|-------------|
|
||||
| `id` | - | - |
|
||||
| `participant` | - | - |
|
||||
| `last_message` | - | - |
|
||||
| `unread_count` | - | - |
|
||||
| `updated_at` | - | - |
|
||||
|
||||
---
|
||||
|
||||
## AuthResponse
|
||||
|
||||
Authentication response.
|
||||
|
||||
### Fields
|
||||
|
||||
| Field | Type | Description |
|
||||
|-------|------|-------------|
|
||||
| `success` | - | - |
|
||||
| `user_id` | - | - |
|
||||
| `username` | - | - |
|
||||
| `web_auth_token` | - | - |
|
||||
| `message` | - | - |
|
||||
|
||||
---
|
||||
|
||||
## ErrorDetail
|
||||
|
||||
Error detail from API.
|
||||
|
||||
### Fields
|
||||
|
||||
| Field | Type | Description |
|
||||
|-------|------|-------------|
|
||||
| `code` | - | - |
|
||||
| `message` | - | - |
|
||||
| `field` | - | - |
|
||||
|
||||
---
|
||||
|
||||
## APIErrorResponse
|
||||
|
||||
Standard API error response.
|
||||
|
||||
### Fields
|
||||
|
||||
| Field | Type | Description |
|
||||
|-------|------|-------------|
|
||||
| `success` | - | - |
|
||||
| `errors` | - | - |
|
||||
| `message` | - | - |
|
||||
|
||||
---
|
||||
|
||||
## City
|
||||
|
||||
City information.
|
||||
|
||||
### Fields
|
||||
|
||||
| Field | Type | Description |
|
||||
|-------|------|-------------|
|
||||
| `id` | - | - |
|
||||
| `name` | - | - |
|
||||
| `country_id` | - | - |
|
||||
|
||||
---
|
||||
|
||||
## Country
|
||||
|
||||
Country information.
|
||||
|
||||
### Fields
|
||||
|
||||
| Field | Type | Description |
|
||||
|-------|------|-------------|
|
||||
| `id` | - | - |
|
||||
| `name` | - | - |
|
||||
| `code` | - | - |
|
||||
| `cities` | - | - |
|
||||
|
||||
---
|
||||
|
||||
## TimeZone
|
||||
|
||||
Timezone information.
|
||||
|
||||
### Fields
|
||||
|
||||
| Field | Type | Description |
|
||||
|-------|------|-------------|
|
||||
| `id` | - | - |
|
||||
| `name` | - | - |
|
||||
| `offset` | - | - |
|
||||
|
||||
---
|
||||
|
||||
## Feature
|
||||
|
||||
Feature/addon information.
|
||||
|
||||
### Fields
|
||||
|
||||
| Field | Type | Description |
|
||||
|-------|------|-------------|
|
||||
| `id` | - | - |
|
||||
| `name` | - | - |
|
||||
| `description` | - | - |
|
||||
| `price` | - | - |
|
||||
| `type` | - | - |
|
||||
|
||||
---
|
||||
|
||||
## Badge
|
||||
|
||||
User badge information.
|
||||
|
||||
### Fields
|
||||
|
||||
| Field | Type | Description |
|
||||
|-------|------|-------------|
|
||||
| `id` | - | - |
|
||||
| `name` | - | - |
|
||||
| `description` | - | - |
|
||||
| `icon_url` | - | - |
|
||||
|
||||
---
|
||||
|
||||
## DataResponse
|
||||
|
||||
Generic data response wrapper.
|
||||
|
||||
### Fields
|
||||
|
||||
| Field | Type | Description |
|
||||
|-------|------|-------------|
|
||||
| `success` | - | - |
|
||||
| `data` | - | - |
|
||||
| `message` | - | - |
|
||||
|
||||
---
|
||||
|
||||
|
||||
# Errors
|
||||
|
||||
Exception classes for error handling.
|
||||
|
||||
## KworkError
|
||||
|
||||
Base exception for all Kwork API errors.
|
||||
|
||||
---
|
||||
|
||||
## KworkAuthError
|
||||
|
||||
Authentication/authorization error.
|
||||
|
||||
---
|
||||
|
||||
## KworkApiError
|
||||
|
||||
API request error (4xx, 5xx).
|
||||
|
||||
---
|
||||
|
||||
## KworkNotFoundError
|
||||
|
||||
Resource not found (404).
|
||||
|
||||
---
|
||||
|
||||
## KworkRateLimitError
|
||||
|
||||
Rate limit exceeded (429).
|
||||
|
||||
---
|
||||
|
||||
## KworkValidationError
|
||||
|
||||
Validation error (400).
|
||||
|
||||
---
|
||||
|
||||
## KworkNetworkError
|
||||
|
||||
Network/connection error.
|
||||
|
||||
---
|
||||
212
docs/examples.md
Normal file
212
docs/examples.md
Normal file
@ -0,0 +1,212 @@
|
||||
# Usage Examples
|
||||
|
||||
## Catalog
|
||||
|
||||
### Get Catalog List
|
||||
|
||||
```python
|
||||
from kwork_api import KworkClient
|
||||
|
||||
async with KworkClient(token="token") as client:
|
||||
catalog = await client.catalog.get_list(page=1, category_id=5)
|
||||
|
||||
for kwork in catalog.kworks:
|
||||
print(f"{kwork.title}: {kwork.price} RUB")
|
||||
|
||||
# Pagination
|
||||
if catalog.pagination:
|
||||
print(f"Page {catalog.pagination.current_page} of {catalog.pagination.total_pages}")
|
||||
```
|
||||
|
||||
### Get Kwork Details
|
||||
|
||||
```python
|
||||
details = await client.catalog.get_details(kwork_id=123)
|
||||
|
||||
print(f"Title: {details.title}")
|
||||
print(f"Price: {details.price}")
|
||||
print(f"Description: {details.full_description}")
|
||||
print(f"Delivery: {details.delivery_time} days")
|
||||
```
|
||||
|
||||
## Projects
|
||||
|
||||
### Get Projects List
|
||||
|
||||
```python
|
||||
projects = await client.projects.get_list(page=1)
|
||||
|
||||
for project in projects.projects:
|
||||
print(f"{project.title} - {project.budget} RUB")
|
||||
```
|
||||
|
||||
### Get Customer Orders
|
||||
|
||||
```python
|
||||
orders = await client.projects.get_payer_orders()
|
||||
|
||||
for order in orders:
|
||||
print(f"Order #{order.id}: {order.status}")
|
||||
```
|
||||
|
||||
### Get Performer Orders
|
||||
|
||||
```python
|
||||
orders = await client.projects.get_worker_orders()
|
||||
|
||||
for order in orders:
|
||||
print(f"Work #{order.id}: {order.status}")
|
||||
```
|
||||
|
||||
## User
|
||||
|
||||
### Get User Info
|
||||
|
||||
```python
|
||||
user_info = await client.user.get_info()
|
||||
print(f"Username: {user_info.get('username')}")
|
||||
```
|
||||
|
||||
### Get Reviews
|
||||
|
||||
```python
|
||||
reviews = await client.user.get_reviews(page=1)
|
||||
|
||||
for review in reviews.reviews:
|
||||
print(f"Rating: {review.rating}/5 - {review.comment}")
|
||||
```
|
||||
|
||||
### Get Favorite Kworks
|
||||
|
||||
```python
|
||||
favorites = await client.user.get_favorite_kworks()
|
||||
|
||||
for kwork in favorites:
|
||||
print(f"Favorite: {kwork.title}")
|
||||
```
|
||||
|
||||
## Reference Data
|
||||
|
||||
### Get Cities
|
||||
|
||||
```python
|
||||
cities = await client.reference.get_cities()
|
||||
|
||||
for city in cities:
|
||||
print(f"{city.id}: {city.name}")
|
||||
```
|
||||
|
||||
### Get Countries
|
||||
|
||||
```python
|
||||
countries = await client.reference.get_countries()
|
||||
|
||||
for country in countries:
|
||||
print(f"{country.id}: {country.name}")
|
||||
```
|
||||
|
||||
### Get Timezones
|
||||
|
||||
```python
|
||||
timezones = await client.reference.get_timezones()
|
||||
|
||||
for tz in timezones:
|
||||
print(f"{tz.id}: {tz.name} ({tz.offset})")
|
||||
```
|
||||
|
||||
## Notifications
|
||||
|
||||
### Get Notifications
|
||||
|
||||
```python
|
||||
notifications = await client.notifications.get_list()
|
||||
|
||||
for notif in notifications.notifications:
|
||||
print(f"{notif.title}: {notif.message}")
|
||||
|
||||
print(f"Unread: {notifications.unread_count}")
|
||||
```
|
||||
|
||||
### Fetch New Notifications
|
||||
|
||||
```python
|
||||
new_notifications = await client.notifications.fetch()
|
||||
print(f"New: {len(new_notifications.notifications)}")
|
||||
```
|
||||
|
||||
### Get Dialogs
|
||||
|
||||
```python
|
||||
dialogs = await client.notifications.get_dialogs()
|
||||
|
||||
for dialog in dialogs:
|
||||
print(f"Dialog with {dialog.participant.username}: {dialog.last_message}")
|
||||
```
|
||||
|
||||
## Error Handling
|
||||
|
||||
```python
|
||||
from kwork_api import KworkAuthError, KworkApiError, KworkNotFoundError
|
||||
|
||||
try:
|
||||
catalog = await client.catalog.get_list()
|
||||
except KworkAuthError as e:
|
||||
print(f"Authentication failed: {e}")
|
||||
except KworkNotFoundError as e:
|
||||
print(f"Resource not found: {e}")
|
||||
except KworkApiError as e:
|
||||
print(f"API error [{e.status_code}]: {e.message}")
|
||||
except Exception as e:
|
||||
print(f"Unexpected error: {e}")
|
||||
```
|
||||
|
||||
## Rate Limiting
|
||||
|
||||
```python
|
||||
import asyncio
|
||||
|
||||
async def fetch_all_pages():
|
||||
all_kworks = []
|
||||
|
||||
for page in range(1, 10):
|
||||
try:
|
||||
catalog = await client.catalog.get_list(page=page)
|
||||
all_kworks.extend(catalog.kworks)
|
||||
|
||||
if not catalog.pagination or not catalog.pagination.has_next:
|
||||
break
|
||||
|
||||
# Delay to avoid rate limiting
|
||||
await asyncio.sleep(1)
|
||||
|
||||
except KworkRateLimitError:
|
||||
print("Rate limited, waiting...")
|
||||
await asyncio.sleep(5)
|
||||
|
||||
return all_kworks
|
||||
```
|
||||
|
||||
## Pagination Helper
|
||||
|
||||
```python
|
||||
async def fetch_all_catalog():
|
||||
"""Fetch all kworks from catalog with pagination."""
|
||||
all_kworks = []
|
||||
page = 1
|
||||
|
||||
while True:
|
||||
catalog = await client.catalog.get_list(page=page)
|
||||
all_kworks.extend(catalog.kworks)
|
||||
|
||||
if not catalog.pagination or not catalog.pagination.has_next:
|
||||
break
|
||||
|
||||
page += 1
|
||||
await asyncio.sleep(0.5) # Rate limiting
|
||||
|
||||
return all_kworks
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
*More examples in the API Reference.*
|
||||
81
docs/index.md
Normal file
81
docs/index.md
Normal file
@ -0,0 +1,81 @@
|
||||
# Kwork API Documentation
|
||||
|
||||
Unofficial Python client for Kwork.ru API.
|
||||
|
||||
## Quick Start
|
||||
|
||||
### Installation
|
||||
|
||||
```bash
|
||||
pip install kwork-api
|
||||
```
|
||||
|
||||
### Authentication
|
||||
|
||||
```python
|
||||
from kwork_api import KworkClient
|
||||
|
||||
# Login with credentials
|
||||
client = await KworkClient.login("username", "password")
|
||||
|
||||
# Or restore from token
|
||||
client = KworkClient(token="your_web_auth_token")
|
||||
```
|
||||
|
||||
### Basic Usage
|
||||
|
||||
```python
|
||||
async with KworkClient(token="token") as client:
|
||||
# Get catalog
|
||||
catalog = await client.catalog.get_list(page=1)
|
||||
|
||||
# Get kwork details
|
||||
details = await client.catalog.get_details(kwork_id=123)
|
||||
|
||||
# Get projects
|
||||
projects = await client.projects.get_list()
|
||||
```
|
||||
|
||||
## Documentation Sections
|
||||
|
||||
- **[API Reference](api-reference.md)** — All endpoints and methods
|
||||
- **[Models](api-reference.md#models)** — Pydantic models
|
||||
- **[Errors](api-reference.md#errors)** — Exception classes
|
||||
- **[Examples](examples.md)** — Usage examples
|
||||
|
||||
## Features
|
||||
|
||||
- ✅ Full API coverage (45 endpoints)
|
||||
- ✅ Async/await support
|
||||
- ✅ Pydantic models for type safety
|
||||
- ✅ Clear error handling
|
||||
- ✅ Session management
|
||||
|
||||
## Rate Limiting
|
||||
|
||||
Rate limiting is **not** implemented in the library. Handle it in your code:
|
||||
|
||||
```python
|
||||
import asyncio
|
||||
|
||||
for page in range(1, 10):
|
||||
catalog = await client.catalog.get_list(page=page)
|
||||
await asyncio.sleep(1) # 1 second delay
|
||||
```
|
||||
|
||||
## Error Handling
|
||||
|
||||
```python
|
||||
from kwork_api import KworkAuthError, KworkApiError
|
||||
|
||||
try:
|
||||
catalog = await client.catalog.get_list()
|
||||
except KworkAuthError as e:
|
||||
print(f"Auth failed: {e}")
|
||||
except KworkApiError as e:
|
||||
print(f"API error [{e.status_code}]: {e.message}")
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
*Documentation auto-generated from source code.*
|
||||
193
scripts/generate_docs.py
Normal file
193
scripts/generate_docs.py
Normal file
@ -0,0 +1,193 @@
|
||||
#!/usr/bin/env python3
|
||||
"""
|
||||
Generate API documentation from docstrings.
|
||||
|
||||
Usage:
|
||||
python scripts/generate_docs.py
|
||||
|
||||
Generates docs/api-reference.md from source code docstrings.
|
||||
"""
|
||||
|
||||
import ast
|
||||
import inspect
|
||||
from pathlib import Path
|
||||
from typing import List, Tuple
|
||||
|
||||
|
||||
def extract_class_info(class_node: ast.ClassDef, source_lines: List[str]) -> dict:
|
||||
"""Extract class information including docstring and methods."""
|
||||
info = {
|
||||
"name": class_node.name,
|
||||
"docstring": ast.get_docstring(class_node) or "",
|
||||
"methods": [],
|
||||
}
|
||||
|
||||
for node in class_node.body:
|
||||
if isinstance(node, ast.FunctionDef) and not node.name.startswith("_"):
|
||||
method_info = {
|
||||
"name": node.name,
|
||||
"docstring": ast.get_docstring(node) or "",
|
||||
"args": [],
|
||||
"returns": "",
|
||||
}
|
||||
|
||||
# Extract arguments
|
||||
for arg in node.args.args:
|
||||
if arg.arg not in ("self", "cls"):
|
||||
method_info["args"].append(arg.arg)
|
||||
|
||||
info["methods"].append(method_info)
|
||||
|
||||
return info
|
||||
|
||||
|
||||
def parse_module(file_path: Path) -> List[dict]:
|
||||
"""Parse Python module and extract classes with methods."""
|
||||
source = file_path.read_text()
|
||||
source_lines = source.splitlines()
|
||||
tree = ast.parse(source)
|
||||
|
||||
classes = []
|
||||
for node in ast.walk(tree):
|
||||
if isinstance(node, ast.ClassDef):
|
||||
classes.append(extract_class_info(node, source_lines))
|
||||
|
||||
return classes
|
||||
|
||||
|
||||
def generate_api_reference(src_dir: Path, output_path: Path):
|
||||
"""Generate API reference markdown from source code."""
|
||||
|
||||
# Parse client.py
|
||||
client_path = src_dir / "client.py"
|
||||
classes = parse_module(client_path)
|
||||
|
||||
# Generate markdown
|
||||
md_lines = [
|
||||
"# API Reference",
|
||||
"",
|
||||
"Auto-generated API documentation.",
|
||||
"",
|
||||
"Last updated: " + Path().cwd().name, # Will be updated with date
|
||||
"",
|
||||
"---",
|
||||
"",
|
||||
]
|
||||
|
||||
for cls in classes:
|
||||
if not cls["docstring"]:
|
||||
continue
|
||||
|
||||
md_lines.append(f"## {cls['name']}")
|
||||
md_lines.append("")
|
||||
md_lines.append(cls["docstring"])
|
||||
md_lines.append("")
|
||||
|
||||
if cls["methods"]:
|
||||
md_lines.append("### Methods")
|
||||
md_lines.append("")
|
||||
|
||||
for method in cls["methods"]:
|
||||
args_str = ", ".join(method["args"])
|
||||
md_lines.append(f"#### `{method['name']}({args_str})`")
|
||||
md_lines.append("")
|
||||
|
||||
if method["docstring"]:
|
||||
md_lines.append(method["docstring"])
|
||||
md_lines.append("")
|
||||
|
||||
md_lines.append("")
|
||||
|
||||
md_lines.append("---")
|
||||
md_lines.append("")
|
||||
|
||||
# Parse models.py
|
||||
models_path = src_dir / "models.py"
|
||||
if models_path.exists():
|
||||
model_classes = parse_module(models_path)
|
||||
|
||||
md_lines.append("")
|
||||
md_lines.append("# Models")
|
||||
md_lines.append("")
|
||||
md_lines.append("Pydantic models used in API responses.")
|
||||
md_lines.append("")
|
||||
|
||||
for cls in model_classes:
|
||||
if cls["name"].startswith("_"):
|
||||
continue
|
||||
|
||||
md_lines.append(f"## {cls['name']}")
|
||||
md_lines.append("")
|
||||
|
||||
if cls["docstring"]:
|
||||
md_lines.append(cls["docstring"])
|
||||
md_lines.append("")
|
||||
|
||||
# Show fields
|
||||
md_lines.append("### Fields")
|
||||
md_lines.append("")
|
||||
md_lines.append("| Field | Type | Description |")
|
||||
md_lines.append("|-------|------|-------------|")
|
||||
|
||||
# Extract fields from class body
|
||||
for node in ast.walk(ast.parse(models_path.read_text())):
|
||||
if isinstance(node, ast.ClassDef) and node.name == cls["name"]:
|
||||
for item in node.body:
|
||||
if isinstance(item, ast.AnnAssign) and isinstance(item.target, ast.Name):
|
||||
field_name = item.target.id
|
||||
if not field_name.startswith("_"):
|
||||
md_lines.append(f"| `{field_name}` | - | - |")
|
||||
|
||||
md_lines.append("")
|
||||
md_lines.append("---")
|
||||
md_lines.append("")
|
||||
|
||||
# Parse errors.py
|
||||
errors_path = src_dir / "errors.py"
|
||||
if errors_path.exists():
|
||||
error_classes = parse_module(errors_path)
|
||||
|
||||
md_lines.append("")
|
||||
md_lines.append("# Errors")
|
||||
md_lines.append("")
|
||||
md_lines.append("Exception classes for error handling.")
|
||||
md_lines.append("")
|
||||
|
||||
for cls in error_classes:
|
||||
if cls["name"].startswith("_"):
|
||||
continue
|
||||
|
||||
md_lines.append(f"## {cls['name']}")
|
||||
md_lines.append("")
|
||||
|
||||
if cls["docstring"]:
|
||||
md_lines.append(cls["docstring"])
|
||||
md_lines.append("")
|
||||
|
||||
md_lines.append("---")
|
||||
md_lines.append("")
|
||||
|
||||
# Write output
|
||||
output_path.parent.mkdir(parents=True, exist_ok=True)
|
||||
output_path.write_text("\n".join(md_lines))
|
||||
print(f"✅ Generated {output_path}")
|
||||
|
||||
|
||||
def main():
|
||||
"""Main entry point."""
|
||||
import sys
|
||||
|
||||
# Paths
|
||||
root_dir = Path(__file__).parent.parent
|
||||
src_dir = root_dir / "src" / "kwork_api"
|
||||
output_path = root_dir / "docs" / "api-reference.md"
|
||||
|
||||
if not src_dir.exists():
|
||||
print(f"❌ Source directory not found: {src_dir}")
|
||||
sys.exit(1)
|
||||
|
||||
generate_api_reference(src_dir, output_path)
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
main()
|
||||
Loading…
Reference in New Issue
Block a user