fix openapi documentation for endpoints to make it more LLM friendly, fix content of SwaggerUI H1, make the ingest POST endpoint accept JSON headers instead of weird application/x-www-form which's better for LLM and API integration

ix-56h · ix-56h · commit b90a42ac5390 · 2025-07-03T16:53:34.000+02:00
diff --git a/src/server/main.py b/src/server/main.py
@@ -49,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"}
diff --git a/src/server/routers/ingest.py b/src/server/routers/ingest.py
@@ -3,8 +3,7 @@
 from fastapi import APIRouter, Request, status
 from fastapi.responses import JSONResponse
 
-from server.form_types import IntForm, OptStrForm, StrForm
-from server.models import IngestErrorResponse, IngestRequest, IngestSuccessResponse, PatternType
+from server.models import IngestErrorResponse, IngestRequest, IngestSuccessResponse
 from server.query_processor import process_query
 from server.server_utils import limiter
 
@@ -21,50 +20,25 @@
 )
 @limiter.limit("10/minute")
 async def api_ingest(
-    request: Request,  # noqa: ARG001 (unused) pylint: disable=unused-argument
-    input_text: StrForm,
-    max_file_size: IntForm,
-    pattern_type: StrForm = "exclude",
-    pattern: StrForm = "",
-    token: OptStrForm = None,
+    request: Request,  # noqa: ARG001
+    ingest_request: IngestRequest,
 ) -> JSONResponse:
     """Ingest a Git repository and return processed content.
 
-    This endpoint processes a Git repository by cloning it, analyzing its structure,
+    **This endpoint processes a Git repository by cloning it, analyzing its structure,**
     and returning a summary with the repository's content. The response includes
     file tree structure, processed content, and metadata about the ingestion.
 
-    Parameters
-    ----------
-    request : Request
-        FastAPI request object
-    input_text : StrForm
-        Git repository URL or slug to ingest
-    max_file_size : IntForm
-        Maximum file size slider position (0-500) for filtering files
-    pattern_type : StrForm
-        Type of pattern to use for file filtering ("include" or "exclude")
-    pattern : StrForm
-        Glob/regex pattern string for file filtering
-    token : OptStrForm
-        GitHub personal access token (PAT) for accessing private repositories
+    **Parameters**
 
-    Returns
-    -------
-    JSONResponse
-        Success response with ingestion results or error response with appropriate HTTP status code
+    - **ingest_request** (`IngestRequest`): Pydantic model containing ingestion parameters
 
-    """
-    try:
-        # Validate input using Pydantic model
-        ingest_request = IngestRequest(
-            input_text=input_text,
-            max_file_size=max_file_size,
-            pattern_type=PatternType(pattern_type),
-            pattern=pattern,
-            token=token,
-        )
+    **Returns**
 
+    - **JSONResponse**: Success response with ingestion results or error response with appropriate HTTP status code
+
+    """  # pylint: disable=unused-argument
+    try:
         result = await process_query(
             input_text=ingest_request.input_text,
             slider_position=ingest_request.max_file_size,
@@ -90,7 +64,7 @@ async def api_ingest(
         # Handle validation errors with 400 status code
         error_response = IngestErrorResponse(
             error=f"Validation error: {ve!s}",
-            repo_url=input_text,
+            repo_url=ingest_request.input_text,
         )
         return JSONResponse(
             status_code=status.HTTP_400_BAD_REQUEST,
@@ -101,7 +75,7 @@ async def api_ingest(
         # Handle unexpected errors with 500 status code
         error_response = IngestErrorResponse(
             error=f"Internal server error: {exc!s}",
-            repo_url=input_text,
+            repo_url=ingest_request.input_text,
         )
         return JSONResponse(
             status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
diff --git a/src/server/templates/swagger_ui.jinja b/src/server/templates/swagger_ui.jinja
@@ -2,37 +2,14 @@
 {% block title %}API Docs{% endblock %}
 {% block content %}
     <div class="mb-8">
-        <div class="relative w-full mx-auto flex sm:flex-row flex-col justify-center items-start sm:items-center">
-            <svg class="h-auto w-16 sm:w-20 md:w-24 flex-shrink-0 p-2 md:relative sm:absolute lg:absolute left-0 lg:-translate-x-full lg:ml-32 md:translate-x-10 sm:-translate-y-16 md:-translate-y-0 -translate-x-2 lg:-translate-y-10"
-                 viewBox="0 0 91 98"
-                 fill="none"
-                 xmlns="http://www.w3.org/2000/svg">
-                <path d="m35.878 14.162 1.333-5.369 1.933 5.183c4.47 11.982 14.036 21.085 25.828 24.467l5.42 1.555-5.209 2.16c-11.332 4.697-19.806 14.826-22.888 27.237l-1.333 5.369-1.933-5.183C34.56 57.599 24.993 48.496 13.201 45.114l-5.42-1.555 5.21-2.16c11.331-4.697 19.805-14.826 22.887-27.237Z" fill="#FE4A60" stroke="#000" stroke-width="3.445">
-                </path>
-                <path d="M79.653 5.729c-2.436 5.323-9.515 15.25-18.341 12.374m9.197 16.336c2.6-5.851 10.008-16.834 18.842-13.956m-9.738-15.07c-.374 3.787 1.076 12.078 9.869 14.943M70.61 34.6c.503-4.21-.69-13.346-9.49-16.214M14.922 65.967c1.338 5.677 6.372 16.756 15.808 15.659M18.21 95.832c-1.392-6.226-6.54-18.404-15.984-17.305m12.85-12.892c-.41 3.771-3.576 11.588-12.968 12.681M18.025 96c.367-4.21 3.453-12.905 12.854-14" stroke="#000" stroke-width="2.548" stroke-linecap="round">
-                </path>
-            </svg>
-            <h1 class="text-4xl sm:text-5xl sm:pt-20 lg:pt-5 md:text-6xl lg:text-7xl font-bold tracking-tighter w-full inline-block text-left md:text-center relative">
-                Gitingest API
-                <br>
-                Documentation
-            </h1>
-            <svg class="w-16 lg:w-20 h-auto lg:absolute flex-shrink-0 right-0 bottom-0 md:block hidden translate-y-10 md:translate-y-20 lg:translate-y-4 lg:-translate-x-12 -translate-x-10"
-                 viewBox="0 0 92 80"
-                 fill="none"
-                 xmlns="http://www.w3.org/2000/svg">
-                <path d="m35.213 16.953.595-5.261 2.644 4.587a35.056 35.056 0 0 0 26.432 17.33l5.261.594-4.587 2.644A35.056 35.056 0 0 0 48.23 63.28l-.595 5.26-2.644-4.587a35.056 35.056 0 0 0-26.432-17.328l-5.261-.595 4.587-2.644a35.056 35.056 0 0 0 17.329-26.433Z" fill="#5CF1A4" stroke="#000" stroke-width="2.868" class="">
-                </path>
-                <path d="M75.062 40.108c1.07 5.255 1.072 16.52-7.472 19.54m7.422-19.682c1.836 2.965 7.643 8.14 16.187 5.121-8.544 3.02-8.207 15.23-6.971 20.957-1.97-3.343-8.044-9.274-16.588-6.254M12.054 28.012c1.34-5.22 6.126-15.4 14.554-14.369M12.035 28.162c-.274-3.487-2.93-10.719-11.358-11.75C9.104 17.443 14.013 6.262 15.414.542c.226 3.888 2.784 11.92 11.212 12.95" stroke="#000" stroke-width="2.319" stroke-linecap="round">
-                </path>
-            </svg>
+        <div class="relative w-full flex sm:flex-row flex-col justify-center sm:items-center">
+            {# Title & Sparkles #}
+            <h1 class="landing-page-title">Gitingest API</h1>
+            <img src="/static/svg/sparkle-red.svg" class="sparkle-red no-drag">
+            <img src="/static/svg/sparkle-green.svg" class="sparkle-green no-drag">
         </div>
-        <p class="text-gray-600 text-lg max-w-2xl mx-auto text-center mt-8">
-            Turn any Git repository into a simple text digest of its codebase.
-        </p>
-        <p class="text-gray-600 text-lg max-w-2xl mx-auto text-center mt-0">
-            This is useful for feeding a codebase into any LLM.
-        </p>
+        <p class="intro-text mt-8">Turn any Git repository into a simple text digest of its codebase.</p>
+        <p class="intro-text mt-0">This is useful for feeding a codebase into any LLM.</p>
     </div>
     <div class="bg-[#fff4da] rounded-xl border-[3px] border-gray-900 p-4 md:p-8 relative z-20">
         <div id="swagger-ui"></div>
diff --git a/src/static/js/utils.js b/src/static/js/utils.js
@@ -72,24 +72,19 @@ function handleSubmit(event, showLoadingSpinner = false) {
     const submitButton = form.querySelector('button[type="submit"]');
     if (!submitButton) return;
 
-    const formData = new FormData(form);
-
-    // Update file size
+    // Collect form values into a plain object
+    let data = {};
+    const inputText = form.querySelector('[name="input_text"]');
+    const token = form.querySelector('[name="token"]');
     const slider = document.getElementById('file_size');
-    if (slider) {
-        formData.delete('max_file_size');
-        formData.append('max_file_size', slider.value);
-    }
-
-    // Update pattern type and pattern
     const patternType = document.getElementById('pattern_type');
     const pattern = document.getElementById('pattern');
-    if (patternType && pattern) {
-        formData.delete('pattern_type');
-        formData.delete('pattern');
-        formData.append('pattern_type', patternType.value);
-        formData.append('pattern', pattern.value);
-    }
+
+    if (inputText) data.input_text = inputText.value;
+    if (token) data.token = token.value;
+    if (slider) data.max_file_size = slider.value;
+    if (patternType) data.pattern_type = patternType.value;
+    if (pattern) data.pattern = pattern.value;
 
     const originalContent = submitButton.innerHTML;
 
@@ -107,8 +102,12 @@ function handleSubmit(event, showLoadingSpinner = false) {
         submitButton.classList.add('bg-[#ffb14d]');
     }
 
-    // Submit the form to /api/ingest
-    fetch('/api/ingest', {method: 'POST', body: formData})
+    // Submit the form to /api/ingest as JSON
+    fetch('/api/ingest', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify(data)
+    })
         .then(response => response.json())
         .then(data => {
             // Hide loading overlay
diff --git a/tests/test_flow_integration.py b/tests/test_flow_integration.py
@@ -56,7 +56,7 @@ async def test_remote_repository_analysis(request: pytest.FixtureRequest) -> Non
         "token": "",
     }
 
-    response = client.post("/api/ingest", data=form_data)
+    response = client.post("/api/ingest", json=form_data)
     assert response.status_code == status.HTTP_200_OK, f"Form submission failed: {response.text}"
 
     # Check that response is JSON
@@ -81,7 +81,7 @@ async def test_invalid_repository_url(request: pytest.FixtureRequest) -> None:
         "token": "",
     }
 
-    response = client.post("/api/ingest", data=form_data)
+    response = client.post("/api/ingest", json=form_data)
     # Should return 400 for invalid repository
     assert response.status_code == status.HTTP_400_BAD_REQUEST, f"Request failed: {response.text}"
 
@@ -104,7 +104,7 @@ async def test_large_repository(request: pytest.FixtureRequest) -> None:
         "token": "",
     }
 
-    response = client.post("/api/ingest", data=form_data)
+    response = client.post("/api/ingest", json=form_data)
     assert response.status_code == status.HTTP_200_OK, f"Request failed: {response.text}"
 
     response_data = response.json()
@@ -128,7 +128,7 @@ def make_request() -> None:
             "pattern": "",
             "token": "",
         }
-        response = client.post("/api/ingest", data=form_data)
+        response = client.post("/api/ingest", json=form_data)
         assert response.status_code == status.HTTP_200_OK, f"Request failed: {response.text}"
 
         response_data = response.json()
@@ -156,7 +156,7 @@ async def test_large_file_handling(request: pytest.FixtureRequest) -> None:
         "token": "",
     }
 
-    response = client.post("/api/ingest", data=form_data)
+    response = client.post("/api/ingest", json=form_data)
     assert response.status_code == status.HTTP_200_OK, f"Request failed: {response.text}"
 
     response_data = response.json()
@@ -179,7 +179,7 @@ async def test_repository_with_patterns(request: pytest.FixtureRequest) -> None:
         "token": "",
     }
 
-    response = client.post("/api/ingest", data=form_data)
+    response = client.post("/api/ingest", json=form_data)
     assert response.status_code == status.HTTP_200_OK, f"Request failed: {response.text}"
 
     response_data = response.json()
