add-swage docs

src/server/main.py

@@ -3,14 +3,13 @@ import io
 from time import time
 from typing import List, Optional
 from abc import ABC, abstractmethod
-from pydantic import BaseModel, Field
-
 
 import uvicorn
-from fastapi import Depends, FastAPI, File, HTTPException, Query, Request, UploadFile, Form
+from fastapi import Depends, FastAPI, File, HTTPException, Query, Request, UploadFile, Form, Security
 from fastapi.middleware.cors import CORSMiddleware
 from fastapi.responses import JSONResponse, RedirectResponse, StreamingResponse
-from pydantic import BaseModel, field_validator
+from fastapi.security import OAuth2PasswordBearer
+from pydantic import BaseModel, field_validator, Field
 from slowapi import Limiter
 from slowapi.util import get_remote_address
 import requests
@@ -25,12 +24,28 @@ from config.logging_config import logger
 
 settings = Settings()
 
+# Define OAuth2 scheme explicitly for Swagger
+oauth2_scheme = OAuth2PasswordBearer(tokenUrl="/v1/token")
+
 # FastAPI app setup with enhanced docs
 app = FastAPI(
     title="Dhwani API",
-    description="A multilingual AI-powered API supporting Indian languages for chat, text-to-speech, audio processing, and transcription.",
+    description="A multilingual AI-powered API supporting Indian languages for chat, text-to-speech, audio processing, and transcription. "
+                "**Authentication Guide:** \n"
+                "1. Register a new user via `/v1/register` with a POST request containing `username` and `password`. \n"
+                "2. Obtain an access token by sending a POST request to `/v1/token` with `username` and `password`. \n"
+                "3. Click the 'Authorize' button (top-right), enter `Bearer <your_access_token>` in the 'bearerAuth' field, and click 'Authorize'. \n"
+                "All protected endpoints require this token for access.",
     version="1.0.0",
     redirect_slashes=False,
+    openapi_tags=[
+        {"name": "Utility", "description": "General utility endpoints"},
+        {"name": "Authentication", "description": "User authentication and registration"},
+        {"name": "Chat", "description": "Chat-related endpoints"},
+        {"name": "Audio", "description": "Audio processing and TTS endpoints"},
+        {"name": "Translation", "description": "Text translation endpoints"}
+    ],
+    swagger_ui_oauth2_redirect_url="/docs/oauth2-redirect",
 )
 
 app.add_middleware(
@@ -137,7 +152,7 @@ async def home():
 @app.post("/v1/token", 
           response_model=TokenResponse,
           summary="User Login",
-          description="Authenticate a user with username and password to obtain an access token.",
+          description="Authenticate a user with username and password to obtain an access token. Copy the token and use it in the 'Authorize' button above.",
           tags=["Authentication"],
           responses={
               200: {"description": "Successful login", "model": TokenResponse},
@@ -161,7 +176,7 @@ async def refresh(token_response: TokenResponse = Depends(refresh_token)):
 @app.post("/v1/register", 
           response_model=TokenResponse,
           summary="Register New User",
-          description="Create a new user account and return an access token.",
+          description="Create a new user account and return an access token. Use this token for subsequent requests.",
           tags=["Authentication"],
           responses={
               200: {"description": "User registered successfully", "model": TokenResponse},
@@ -172,11 +187,12 @@ async def register_user(register_request: RegisterRequest):
 
 @app.post("/v1/audio/speech",
           summary="Generate Speech from Text",
-          description="Convert text to speech in the specified format using an external TTS service. Rate limited to 5 requests per minute per user.",
+          description="Convert text to speech in the specified format using an external TTS service. Rate limited to 5 requests per minute per user. Requires authentication.",
           tags=["Audio"],
           responses={
               200: {"description": "Audio stream", "content": {"audio/mp3": {"example": "Binary audio data"}}},
               400: {"description": "Invalid input"},
+              401: {"description": "Unauthorized - Token required"},
               429: {"description": "Rate limit exceeded"},
               504: {"description": "TTS service timeout"}
           })
@@ -247,11 +263,12 @@ class ChatResponse(BaseModel):
 @app.post("/v1/chat", 
           response_model=ChatResponse,
           summary="Chat with AI",
-          description="Generate a chat response from a prompt in the specified language. Rate limited to 100 requests per minute per user.",
+          description="Generate a chat response from a prompt in the specified language. Rate limited to 100 requests per minute per user. Requires authentication.",
           tags=["Chat"],
           responses={
               200: {"description": "Chat response", "model": ChatResponse},
               400: {"description": "Invalid prompt"},
+              401: {"description": "Unauthorized - Token required"},
               429: {"description": "Rate limit exceeded"},
               504: {"description": "Chat service timeout"}
           })
@@ -302,10 +319,11 @@ async def chat(
 @app.post("/v1/process_audio/", 
           response_model=AudioProcessingResponse,
           summary="Process Audio File",
-          description="Process an uploaded audio file in the specified language. Rate limited to 100 requests per minute per user.",
+          description="Process an uploaded audio file in the specified language. Rate limited to 100 requests per minute per user. Requires authentication.",
           tags=["Audio"],
           responses={
               200: {"description": "Processed result", "model": AudioProcessingResponse},
+              401: {"description": "Unauthorized - Token required"},
               429: {"description": "Rate limit exceeded"},
               504: {"description": "Audio processing timeout"}
           })
@@ -350,10 +368,11 @@ async def process_audio(
 @app.post("/v1/transcribe/", 
           response_model=TranscriptionResponse,
           summary="Transcribe Audio File",
-          description="Transcribe an uploaded audio file into text in the specified language.",
+          description="Transcribe an uploaded audio file into text in the specified language. Requires authentication.",
           tags=["Audio"],
           responses={
               200: {"description": "Transcription result", "model": TranscriptionResponse},
+              401: {"description": "Unauthorized - Token required"},
               504: {"description": "Transcription service timeout"}
           })
 async def transcribe_audio(
@@ -387,11 +406,12 @@ async def transcribe_audio(
 @app.post("/v1/chat_v2", 
           response_model=TranscriptionResponse,
           summary="Chat with Image (V2)",
-          description="Generate a response from a text prompt and optional image. Rate limited to 100 requests per minute per user.",
+          description="Generate a response from a text prompt and optional image. Rate limited to 100 requests per minute per user. Requires authentication.",
           tags=["Chat"],
           responses={
               200: {"description": "Chat response", "model": TranscriptionResponse},
               400: {"description": "Invalid prompt"},
+              401: {"description": "Unauthorized - Token required"},
               429: {"description": "Rate limit exceeded"}
           })
 @limiter.limit(settings.chat_rate_limit)
@@ -443,10 +463,11 @@ class TranslationResponse(BaseModel):
 @app.post("/v1/translate", 
           response_model=TranslationResponse,
           summary="Translate Text",
-          description="Translate a list of sentences from source to target language.",
+          description="Translate a list of sentences from source to target language. Requires authentication.",
           tags=["Translation"],
           responses={
               200: {"description": "Translation result", "model": TranslationResponse},
+              401: {"description": "Unauthorized - Token required"},
               500: {"description": "Translation service error"},
               504: {"description": "Translation service timeout"}
           })