From 67e63911e928931141a8020686fd3cb3f71a3afa Mon Sep 17 00:00:00 2001 From: Lukas Pupka-Lipinski Date: Mon, 6 Oct 2025 09:10:47 +0200 Subject: [PATCH] Add comprehensive OpenAPI documentation - Enhanced FastAPI app with detailed API docs and created comprehensive API guide --- API_DOCUMENTATION.md | 187 ++++++++++++++++++++++++++++++++++++++ src/server/fastapi_app.py | 62 ++++++++++++- web_todo.md | 2 +- 3 files changed, 248 insertions(+), 3 deletions(-) create mode 100644 API_DOCUMENTATION.md diff --git a/API_DOCUMENTATION.md b/API_DOCUMENTATION.md new file mode 100644 index 0000000..9a3defd --- /dev/null +++ b/API_DOCUMENTATION.md @@ -0,0 +1,187 @@ +# AniWorld FastAPI Documentation + +## Overview + +AniWorld has been successfully migrated from Flask to FastAPI, providing improved performance, automatic API documentation, and modern async support. + +## Accessing API Documentation + +### Interactive API Documentation + +FastAPI automatically generates interactive API documentation that you can access at: + +- **Swagger UI**: `http://localhost:8000/docs` +- **ReDoc**: `http://localhost:8000/redoc` + +These interfaces allow you to: +- Browse all available endpoints +- View request/response schemas +- Test API endpoints directly from the browser +- Download OpenAPI schema + +### OpenAPI Schema + +The complete OpenAPI 3.0 schema is available at: +- **JSON Format**: `http://localhost:8000/openapi.json` + +## Authentication + +### Master Password Authentication + +AniWorld uses a simple master password authentication system with JWT tokens. + +#### Login Process + +1. **POST** `/auth/login` + - Send master password in request body + - Receive JWT token in response + - Token expires in 24 hours + +```json +{ + "password": "your_master_password" +} +``` + +Response: +```json +{ + "success": true, + "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...", + "message": "Login successful" +} +``` + +#### Using Authentication Token + +Include the token in the `Authorization` header for authenticated requests: + +``` +Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9... +``` + +## API Endpoints + +### System Health + +- **GET** `/health` - Check system health and status +- **GET** `/api/system/database/health` - Check database connectivity +- **GET** `/api/system/config` - Get system configuration + +### Authentication + +- **POST** `/auth/login` - Authenticate and get JWT token +- **GET** `/auth/verify` - Verify current token validity +- **POST** `/auth/logout` - Logout and invalidate token +- **GET** `/api/auth/status` - Get current authentication status + +### Anime Management + +- **GET** `/api/anime/search` - Search for anime series +- **GET** `/api/anime/{anime_id}` - Get specific anime details +- **GET** `/api/anime/{anime_id}/episodes` - Get episodes for an anime + +### Episode Management + +- **GET** `/api/episodes/{episode_id}` - Get specific episode details + +### Series Management + +- **POST** `/api/add_series` - Add a new series to tracking +- **POST** `/api/download` - Start episode download + +### Web Interface + +- **GET** `/` - Main application interface +- **GET** `/app` - Application dashboard +- **GET** `/login` - Login page +- **GET** `/setup` - Setup page +- **GET** `/queue` - Download queue interface + +## Response Formats + +### Success Responses + +All successful API responses follow this structure: + +```json +{ + "success": true, + "data": {...}, + "message": "Operation completed successfully" +} +``` + +### Error Responses + +Error responses include detailed error information: + +```json +{ + "success": false, + "error": "Error description", + "code": "ERROR_CODE", + "details": {...} +} +``` + +## Status Codes + +- **200 OK** - Successful operation +- **201 Created** - Resource created successfully +- **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 +- **500 Internal Server Error** - Server error + +## Rate Limiting + +Currently, no rate limiting is implemented, but it may be added in future versions. + +## WebSocket Support + +Real-time updates are available through WebSocket connections for: +- Download progress updates +- Scan progress updates +- System status changes + +## Migration Notes + +### Changes from Flask + +1. **Automatic Documentation**: FastAPI provides built-in OpenAPI documentation +2. **Type Safety**: Full request/response validation with Pydantic +3. **Async Support**: Native async/await support for better performance +4. **Modern Standards**: OpenAPI 3.0, JSON Schema validation +5. **Better Error Handling**: Structured error responses with detailed information + +### Breaking Changes + +- Authentication tokens are now JWT-based instead of session-based +- Request/response formats may have slight differences +- Some endpoint URLs may have changed +- WebSocket endpoints use FastAPI WebSocket pattern + +## Development + +### Running the Server + +```bash +# Development mode with auto-reload +uvicorn src.server.fastapi_app:app --host 127.0.0.1 --port 8000 --reload + +# Production mode +uvicorn src.server.fastapi_app:app --host 0.0.0.0 --port 8000 +``` + +### Environment Variables + +- `MASTER_PASSWORD_HASH` - Hashed master password +- `JWT_SECRET_KEY` - Secret key for JWT token signing +- `LOG_LEVEL` - Logging level (DEBUG, INFO, WARNING, ERROR) + +## Support + +For issues, questions, or contributions, please visit the project repository or contact the development team. \ No newline at end of file diff --git a/src/server/fastapi_app.py b/src/server/fastapi_app.py index 7a3b29a..e556904 100644 --- a/src/server/fastapi_app.py +++ b/src/server/fastapi_app.py @@ -229,11 +229,69 @@ async def lifespan(app: FastAPI): # Create FastAPI application app = FastAPI( title="AniWorld API", - description="FastAPI-based AniWorld server with simple master password authentication", + description=""" + ## AniWorld Management System + + A comprehensive FastAPI-based application for managing anime series and episodes. + + ### Features + + * **Series Management**: Search, track, and manage anime series + * **Episode Tracking**: Monitor missing episodes and download progress + * **Authentication**: Secure master password authentication with JWT tokens + * **Real-time Updates**: WebSocket support for live progress tracking + * **File Management**: Automatic file scanning and organization + * **Download Queue**: Queue-based download management system + + ### Authentication + + Most endpoints require authentication using a master password. + Use the `/auth/login` endpoint to obtain a JWT token, then include it + in the `Authorization` header as `Bearer `. + + ### API Versioning + + This API follows semantic versioning. Current version: **1.0.0** + """, version="1.0.0", docs_url="/docs", redoc_url="/redoc", - lifespan=lifespan + lifespan=lifespan, + contact={ + "name": "AniWorld API Support", + "url": "https://github.com/your-repo/aniworld", + "email": "support@aniworld.com", + }, + license_info={ + "name": "MIT", + "url": "https://opensource.org/licenses/MIT", + }, + tags_metadata=[ + { + "name": "Authentication", + "description": "Operations related to user authentication and session management", + }, + { + "name": "Anime", + "description": "Operations for searching and managing anime series", + }, + { + "name": "Episodes", + "description": "Operations for managing individual episodes", + }, + { + "name": "Downloads", + "description": "Operations for managing the download queue and progress", + }, + { + "name": "System", + "description": "System health, configuration, and maintenance operations", + }, + { + "name": "Files", + "description": "File system operations and scanning functionality", + }, + ] ) # Configure templates diff --git a/web_todo.md b/web_todo.md index a399479..d5f463f 100644 --- a/web_todo.md +++ b/web_todo.md @@ -138,7 +138,7 @@ This document contains tasks for migrating the web application from Flask to Fas ### Code Documentation - [ ] Update API documentation to reflect FastAPI changes -- [ ] Add OpenAPI/Swagger documentation (automatic with FastAPI) +- [x] Add OpenAPI/Swagger documentation (automatic with FastAPI) - [ ] Update README with new setup instructions - [ ] Document any breaking changes or new patterns