From 93284a90880df8a7432c0a8ed8cef15b1899fcbd Mon Sep 17 00:00:00 2001
From: grabowski <berwn@buildfor.life>
Date: Mon, 11 Aug 2025 16:46:41 +0700
Subject: [PATCH] Add comprehensive API documentation with media type enums

- Added MediaType enum with book, vinyl, cd, cassette options
- Created Pydantic models (SearchRequest, MediaItem) for API documentation
- Added /api/search endpoint with proper type annotations and response models
- Enhanced FastAPI docs with detailed descriptions and parameter explanations
- Media types now clearly visible in /docs and /redoc interfaces
- Improved API usability with structured request/response models
---
 main.py | 64 +++++++++++++++++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 62 insertions(+), 2 deletions(-)

diff --git a/main.py b/main.py
index fa9cf75..77c3158 100644
--- a/main.py
+++ b/main.py
@@ -4,16 +4,47 @@ from fastapi.staticfiles import StaticFiles
 from fastapi.templating import Jinja2Templates
 import httpx
 import asyncio
-from typing import Optional
+from typing import Optional, List
 import json
 import os
 from dotenv import load_dotenv
 import discogs_client as discogs
+from enum import Enum
+from pydantic import BaseModel
 
 # Load environment variables
 load_dotenv()
 
-app = FastAPI(title="Media Inventory App", description="Search for books, vinyl, CDs, and cassettes")
+# Define media types enum for API documentation
+class MediaType(str, Enum):
+    book = "book"
+    vinyl = "vinyl"
+    cd = "cd"
+    cassette = "cassette"
+
+# Pydantic models for API documentation
+class SearchRequest(BaseModel):
+    media_type: MediaType
+    query: str
+    artist: Optional[str] = None
+
+class MediaItem(BaseModel):
+    title: str
+    artist: Optional[str] = None
+    author: Optional[str] = None
+    year: str
+    isbn: Optional[str] = None
+    label: Optional[str] = None
+    format: Optional[str] = None
+    cover_url: Optional[str] = None
+    openlibrary_url: Optional[str] = None
+    discogs_url: Optional[str] = None
+
+app = FastAPI(
+    title="Media Inventory App", 
+    description="Search for books, vinyl records, CDs, and cassettes using OpenLibrary and Discogs APIs",
+    version="1.0.0"
+)
 
 # Mount static files and templates
 app.mount("/static", StaticFiles(directory="static"), name="static")
@@ -28,6 +59,35 @@ async def home(request: Request):
     """Serve the main search form"""
     return templates.TemplateResponse("index.html", {"request": request})
 
+@app.post("/api/search", response_model=List[MediaItem])
+async def api_search_media(search_request: SearchRequest):
+    """
+    Search for media items via API
+    
+    **Media Types:**
+    - `book`: Search books using OpenLibrary API
+    - `vinyl`: Search vinyl records using Discogs API  
+    - `cd`: Search CDs using Discogs API
+    - `cassette`: Search cassettes using Discogs API
+    
+    **Parameters:**
+    - `media_type`: Type of media to search for (required)
+    - `query`: Search query - title, album name, or keywords (required)
+    - `artist`: Artist name for music searches (optional, helps narrow results)
+    
+    **Returns:**
+    List of media items with details like title, artist/author, year, and links to source
+    """
+    if not search_request.query.strip():
+        return []
+    
+    if search_request.media_type == MediaType.book:
+        results = await search_openlibrary(search_request.query)
+    else:  # vinyl, cd, cassette
+        results = await search_discogs(search_request.query, search_request.media_type.value, search_request.artist)
+    
+    return results
+
 @app.post("/search")
 async def search_media(
     request: Request,