MkDocs documentation integration

2025-09-19 21:23:19 +02:00
parent f042616fdd
commit d0924f90c4
8 changed files with 1183 additions and 24 deletions
--- a/docs/api/index.md
+++ b/docs/api/index.md
@@ -0,0 +1,164 @@
+# API Overview
+
+The Letzshop Import API provides comprehensive endpoints for managing products, shops, users, and marketplace imports. This section provides high-level guidance and concepts for working with our API.
+
+## Interactive Documentation
+
+For hands-on API exploration and testing, use our interactive documentation:
+
+!!! tip "Live API Documentation"
+    - **[Swagger UI](http://localhost:8000/docs)** - Interactive API testing interface
+    - **[ReDoc](http://localhost:8000/redoc)** - Clean, readable API reference
+    - **[OpenAPI Spec](http://localhost:8000/openapi.json)** - Machine-readable API specification
+
+## API Structure
+
+### Base URL
+```
+Production: https://api.letzshop.com/api/v1
+Development: http://localhost:8000/api/v1
+```
+
+### API Versioning
+All API endpoints are versioned using URL path versioning:
+- Current version: `v1`
+- All endpoints are prefixed with `/api/v1/`
+
+## Endpoint Categories
+
+### Authentication (`/auth/`)
+- User registration and login
+- Token refresh and validation
+- Password reset workflows
+
+### Admin (`/admin/`)
+- User management (admin only)
+- System statistics
+- Configuration management
+
+### Products (`/products/`)
+- Product CRUD operations
+- Product search and filtering
+- Bulk operations
+
+### Shops (`/shops/`)
+- Shop management
+- Shop-product associations
+- Shop statistics
+
+### Stock (`/stock/`)
+- Inventory management
+- Stock movements
+- Stock reporting
+
+### Marketplace (`/marketplace/`)
+- Import job management
+- CSV file processing
+- Import status tracking
+
+### Statistics (`/stats/`)
+- System-wide statistics
+- User activity metrics
+- Import performance data
+
+## Request/Response Format
+
+### Content Type
+All API endpoints use JSON for request and response bodies:
+```
+Content-Type: application/json
+```
+
+### Standard Response Format
+```json
+{
+  "data": {...},           // Main response data
+  "message": "Success",    // Human-readable message
+  "status": 200           // HTTP status code
+}
+```
+
+### Error Response Format
+```json
+{
+  "detail": "Error description",
+  "type": "validation_error",
+  "errors": [             // Field-specific errors (if applicable)
+    {
+      "field": "email",
+      "message": "Invalid email format"
+    }
+  ]
+}
+```
+
+## Common Patterns
+
+### Pagination
+Most list endpoints support pagination:
+
+```bash
+GET /api/v1/products?skip=0&limit=20
+```
+
+Response includes pagination metadata:
+```json
+{
+  "items": [...],
+  "total": 150,
+  "skip": 0,
+  "limit": 20,
+  "has_next": true
+}
+```
+
+### Filtering and Searching
+Many endpoints support filtering and search:
+
+```bash
+GET /api/v1/products?search=laptop&category=electronics&min_price=100
+```
+
+### Sorting
+Use the `sort` parameter with field names:
+
+```bash
+GET /api/v1/products?sort=name&order=desc
+```
+
+## Status Codes
+
+| Code | Meaning | Description |
+|------|---------|-------------|
+| 200 | OK | Request successful |
+| 201 | Created | Resource created successfully |
+| 204 | No Content | Request successful, no content returned |
+| 400 | Bad Request | Invalid request data |
+| 401 | Unauthorized | Authentication required |
+| 403 | Forbidden | Insufficient permissions |
+| 404 | Not Found | Resource not found |
+| 422 | Unprocessable Entity | Validation error |
+| 429 | Too Many Requests | Rate limit exceeded |
+| 500 | Internal Server Error | Server error |
+
+## Rate Limiting
+
+API endpoints are rate limited to ensure fair usage:
+
+- **Default limit**: 100 requests per minute per IP
+- **Authenticated users**: 1000 requests per minute
+- **Admin users**: 5000 requests per minute
+
+Rate limit headers are included in responses:
+```
+X-RateLimit-Limit: 100
+X-RateLimit-Remaining: 95
+X-RateLimit-Reset: 1640995200
+```
+
+## Next Steps
+
+- **[Authentication Guide](authentication.md)** - Learn about API authentication
+- **[Error Handling](error-handling.md)** - Understanding API errors
+- **[Rate Limiting](rate-limiting.md)** - Rate limiting details
+- **[Interactive Docs](http://localhost:8000/docs)** - Try the API live