Add comprehensive OpenAPI documentation - Enhanced FastAPI app with detailed API docs and created comprehensive API guide

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.

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 <token>`.
+
+    ### 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

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