New swagger UI integration, improve frontend, remove repo_url from api error response, add api endpoints for ingestion and api config json, better docstring for endpoints, fix include/exclude frontend behavior, new download endpoint (#366)

Author: ix-56h

src/server/main.py

@@ -6,20 +6,21 @@
 from pathlib import Path
 
 from dotenv import load_dotenv
-from fastapi import FastAPI
-from fastapi.responses import FileResponse, HTMLResponse
+from fastapi import FastAPI, Request
+from fastapi.responses import FileResponse, HTMLResponse, JSONResponse
 from fastapi.staticfiles import StaticFiles
 from slowapi.errors import RateLimitExceeded
 from starlette.middleware.trustedhost import TrustedHostMiddleware
 
 from server.routers import dynamic, index, ingest
+from server.server_config import templates
 from server.server_utils import lifespan, limiter, rate_limit_exception_handler
 
 # Load environment variables from .env file
 load_dotenv()
 
 # Initialize the FastAPI application with lifespan
-app = FastAPI(lifespan=lifespan)
+app = FastAPI(lifespan=lifespan, docs_url=None, redoc_url=None)
 app.state.limiter = limiter
 
 # Register the custom exception handler for rate limits
@@ -48,10 +49,9 @@
 async def health_check() -> dict[str, str]:
     """Health check endpoint to verify that the server is running.
 
-    Returns
-    -------
-    dict[str, str]
-        A JSON object with a "status" key indicating the server's health status.
+    **Returns**
+
+    - **dict[str, str]**: A JSON object with a "status" key indicating the server's health status.
 
     """
     return {"status": "healthy"}
@@ -61,43 +61,103 @@ async def health_check() -> dict[str, str]:
 async def head_root() -> HTMLResponse:
     """Respond to HTTP HEAD requests for the root URL.
 
-    Mirrors the headers and status code of the index page.
+    **This endpoint mirrors the headers and status code of the index page**
+    for HTTP HEAD requests, providing a lightweight way to check if the server
+    is responding without downloading the full page content.
+
+    **Returns**
 
-    Returns
-    -------
-    HTMLResponse
-        An empty HTML response with appropriate headers.
+    - **HTMLResponse**: An empty HTML response with appropriate headers
 
     """
     return HTMLResponse(content=None, headers={"content-type": "text/html; charset=utf-8"})
 
 
 @app.get("/robots.txt", include_in_schema=False)
 async def robots() -> FileResponse:
-    """Serve the ``robots.txt`` file to guide search engine crawlers.
+    """Serve the robots.txt file to guide search engine crawlers.
+
+    **This endpoint serves the ``robots.txt`` file located in the static directory**
+    to provide instructions to search engine crawlers about which parts of the site
+    they should or should not index.
+
+    **Returns**
 
-    Returns
-    -------
-    FileResponse
-        The ``robots.txt`` file located in the static directory.
+    - **FileResponse**: The ``robots.txt`` file located in the static directory
 
     """
     return FileResponse("static/robots.txt")
 
 
 @app.get("/llms.txt")
 async def llm_txt() -> FileResponse:
-    """Serve the ``llms.txt`` file to provide information about the site to LLMs.
+    """Serve the llm.txt file to provide information about the site to LLMs.
 
-    Returns
-    -------
-    FileResponse
-        The ``llms.txt`` file located in the static directory.
+    **This endpoint serves the ``llms.txt`` file located in the static directory**
+    to provide information about the site to Large Language Models (LLMs)
+    and other AI systems that may be crawling the site.
+
+    **Returns**
+
+    - **FileResponse**: The ``llms.txt`` file located in the static directory
 
     """
     return FileResponse("static/llms.txt")
 
 
+@app.get("/docs", response_class=HTMLResponse, include_in_schema=False)
+async def custom_swagger_ui(request: Request) -> HTMLResponse:
+    """Serve custom Swagger UI documentation.
+
+    **This endpoint serves a custom Swagger UI interface**
+    for the API documentation, providing an interactive way to explore
+    and test the available endpoints.
+
+    **Parameters**
+
+    - **request** (`Request`): The incoming HTTP request
+
+    **Returns**
+
+    - **HTMLResponse**: Custom Swagger UI documentation page
+
+    """
+    return templates.TemplateResponse("swagger_ui.jinja", {"request": request})
+
+
+@app.get("/api", include_in_schema=True)
+def openapi_json_get() -> JSONResponse:
+    """Return the OpenAPI schema.
+
+    **This endpoint returns the OpenAPI schema (openapi.json)**
+    that describes the API structure, endpoints, and data models
+    for documentation and client generation purposes.
+
+    **Returns**
+
+    - **JSONResponse**: The OpenAPI schema as JSON
+
+    """
+    return JSONResponse(app.openapi())
+
+
+@app.api_route("/api", methods=["POST", "PUT", "DELETE", "OPTIONS", "HEAD"], include_in_schema=False)
+@app.api_route("/api/", methods=["GET", "POST", "PUT", "DELETE", "OPTIONS", "HEAD"], include_in_schema=False)
+def openapi_json() -> JSONResponse:
+    """Return the OpenAPI schema for various HTTP methods.
+
+    **This endpoint returns the OpenAPI schema (openapi.json)**
+    for multiple HTTP methods, providing API documentation
+    for clients that may use different request methods.
+
+    **Returns**
+
+    - **JSONResponse**: The OpenAPI schema as JSON
+
+    """
+    return JSONResponse(app.openapi())
+
+
 # Include routers for modular endpoints
 app.include_router(index)
 app.include_router(ingest)

src/server/models.py

@@ -69,6 +69,8 @@ class IngestSuccessResponse(BaseModel):
         Short form of repository URL (user/repo).
     summary : str
         Summary of the ingestion process including token estimates.
+    ingest_id : str
+        Ingestion id used to download full context.
     tree : str
         File tree structure of the repository.
     content : str
@@ -85,6 +87,7 @@ class IngestSuccessResponse(BaseModel):
     repo_url: str = Field(..., description="Original repository URL")
     short_repo_url: str = Field(..., description="Short repository URL (user/repo)")
     summary: str = Field(..., description="Ingestion summary with token estimates")
+    ingest_id: str = Field(..., description="Ingestion id used to download full context")
     tree: str = Field(..., description="File tree structure")
     content: str = Field(..., description="Processed file content")
     default_max_file_size: int = Field(..., description="File size slider position used")
@@ -99,13 +102,10 @@ class IngestErrorResponse(BaseModel):
     ----------
     error : str
         Error message describing what went wrong.
-    repo_url : str
-        The repository URL that failed to process.
 
     """
 
     error: str = Field(..., description="Error message")
-    repo_url: str = Field(..., description="Repository URL that failed")
 
 
 # Union type for API responses

src/server/query_processor.py

@@ -99,7 +99,7 @@ async def process_query(
             print(f"{Colors.BROWN}WARN{Colors.END}: {Colors.RED}<-  {Colors.END}", end="")
             print(f"{Colors.RED}{exc}{Colors.END}")
 
-        return IngestErrorResponse(error=str(exc), repo_url=short_repo_url)
+        return IngestErrorResponse(error=str(exc))
 
     if len(content) > MAX_DISPLAY_SIZE:
         content = (
@@ -122,6 +122,7 @@ async def process_query(
         repo_url=input_text,
         short_repo_url=short_repo_url,
         summary=summary,
+        ingest_id=query.id,
         tree=tree,
         content=content,
         default_max_file_size=slider_position,