Fix /admin route redirect and add OpenAPI/Swagger support

ForceFledgling · ForceFledgling · commit d0b3c3897662 · 2025-12-13T12:13:50.000-05:00
- Add /admin redirect route in admin router before mounting urls_router
- Add OpenAPI/Swagger UI support out of the box
- Fix route ordering to ensure /admin redirect works correctly
- Update example apps to use Starlette instead of FastAPI
diff --git a/example/apps/home/__init__.py b/example/apps/home/__init__.py
@@ -1,4 +1,4 @@
-from fastapi import APIRouter
+from raystack.compat import APIRouter
 
 from .api import router as api_router
 from .urls import router as urls_router
diff --git a/example/apps/home/api.py b/example/apps/home/api.py
@@ -1,4 +1,4 @@
-from fastapi import APIRouter
+from raystack.compat import APIRouter
 
 
 router = APIRouter()
diff --git a/example/apps/home/urls.py b/example/apps/home/urls.py
@@ -1,4 +1,4 @@
-from fastapi import APIRouter
+from raystack.compat import APIRouter
 from . import views
 
 router = APIRouter()
diff --git a/example/apps/home/views.py b/example/apps/home/views.py
@@ -1,5 +1,5 @@
 from raystack.shortcuts import render_template
-from fastapi import Request
+from raystack.compat import Request
 
 # Create your views here.
 
diff --git a/example/config/urls.py b/example/config/urls.py
@@ -1,4 +1,4 @@
-from fastapi import APIRouter, Request
+from raystack.compat import APIRouter, Request
 
 
 router = APIRouter()
diff --git a/example_async/apps/home/__init__.py b/example_async/apps/home/__init__.py
@@ -1,4 +1,4 @@
-from fastapi import APIRouter
+from raystack.compat import APIRouter
 
 from .api import router as api_router
 from .urls import router as urls_router
diff --git a/example_async/apps/home/api.py b/example_async/apps/home/api.py
@@ -1,4 +1,4 @@
-from fastapi import APIRouter
+from raystack.compat import APIRouter
 
 
 router = APIRouter()
diff --git a/example_async/apps/home/deps.py b/example_async/apps/home/deps.py
@@ -1,4 +1,4 @@
-from fastapi import Depends
+from raystack.compat import Depends
 from sqlalchemy.ext.asyncio import AsyncSession
 
 # Use framework functionality for database operations
diff --git a/example_async/apps/home/urls.py b/example_async/apps/home/urls.py
@@ -1,4 +1,4 @@
-from fastapi import APIRouter
+from raystack.compat import APIRouter
 from . import views
 
 router = APIRouter()
diff --git a/example_async/apps/home/views.py b/example_async/apps/home/views.py
@@ -1,5 +1,5 @@
 from raystack.shortcuts import render_template
-from fastapi import Request, Depends
+from raystack.compat import Request, Depends
 from sqlalchemy.ext.asyncio import AsyncSession
 from sqlmodel import select
 
diff --git a/example_async/config/urls.py b/example_async/config/urls.py
@@ -1,4 +1,4 @@
-from fastapi import APIRouter, Request
+from raystack.compat import APIRouter, Request
 
 
 router = APIRouter()
diff --git a/example_async/requirements.txt b/example_async/requirements.txt
@@ -1,5 +1,5 @@
 sqlmodel
-fastapi
+starlette
 uvicorn
 python-jose[cryptography]
 passlib[bcrypt]
diff --git a/src/raystack/__init__.py b/src/raystack/__init__.py
@@ -34,6 +34,8 @@ def __init__(self):
         # Get absolute path to current directory
         self.raystack_directory = os.path.dirname(os.path.abspath(__file__))
         
+        # Include OpenAPI first, before other routers
+        self.include_openapi()
         # Include routers
         self.include_routers()
         self.include_templates()
@@ -50,6 +52,7 @@ def include_routers(self):
 
             # If module contains routers, include them
             if hasattr(module, "router"):
+                # In Starlette, mount routers directly
                 self.mount("", module.router)
                 logger.info(f"✅'{app_path}.router'")
             else:
@@ -103,4 +106,15 @@ def include_middleware(self):
                     self.add_middleware(middleware_class)
                     logger.info(f"✅'{middleware_path}'")
                 except Exception as e:
-                    logger.warning(f"⚠️ Failed to load middleware '{middleware_path}': {e}")
+                    logger.warning(f"⚠️ Failed to load middleware '{middleware_path}': {e}")
+    
+    def include_openapi(self):
+        """Include OpenAPI/Swagger UI documentation."""
+        try:
+            from raystack.contrib.openapi import setup_openapi
+            docs_url = getattr(self.settings, 'DOCS_URL', '/docs')
+            openapi_url = getattr(self.settings, 'OPENAPI_URL', '/openapi.json')
+            setup_openapi(self, docs_url=docs_url, openapi_url=openapi_url)
+            logger.info(f"✅ OpenAPI documentation available at {docs_url}")
+        except Exception as e:
+            logger.warning(f"⚠️ Failed to setup OpenAPI: {e}")
diff --git a/src/raystack/compat.py b/src/raystack/compat.py
@@ -47,42 +47,66 @@ def include_router(self, router: 'APIRouter', prefix: str = "", tags: Optional[l
             combined_tags = self.tags
         
         # Mount the router with the combined prefix
+        # In Starlette, mount() adds a Mount route to the router
         if full_prefix:
-            # Create a new router with the prefix
-            prefixed_router = Router()
-            prefixed_router.mount(full_prefix, router)
-            self.mount("", prefixed_router)
+            # Mount with prefix
+            self.mount(full_prefix, router)
         else:
-            self.mount("", router)
+            # Mount without prefix - add all routes directly to this router
+            # This is needed because mount("", router) doesn't work as expected
+            for route in router.routes:
+                self.routes.append(route)
+    
+    def _filter_starlette_kwargs(self, kwargs: dict) -> dict:
+        """Filter kwargs to only include those supported by Starlette Router."""
+        # Starlette Router.add_route() supports: path, endpoint, methods, name, include_in_schema
+        # FastAPI-specific kwargs to ignore: response_model, tags, dependencies, status_code, etc.
+        supported = {'name', 'include_in_schema'}
+        return {k: v for k, v in kwargs.items() if k in supported}
+    
+    def add_api_route(self, path: str, endpoint: Callable, methods: Optional[list] = None, **kwargs):
+        """
+        FastAPI-compatible method to add a route.
+        Equivalent to add_route but filters FastAPI-specific kwargs.
+        """
+        if methods is None:
+            methods = ["GET"]
+        filtered_kwargs = self._filter_starlette_kwargs(kwargs)
+        return self.add_route(path, endpoint, methods=methods, **filtered_kwargs)
     
     def get(self, path: str, **kwargs):
         """Decorator for GET routes."""
         def decorator(func: Callable):
-            return self.add_route(path, func, methods=["GET"], **kwargs)
+            filtered_kwargs = self._filter_starlette_kwargs(kwargs)
+            return self.add_route(path, func, methods=["GET"], **filtered_kwargs)
         return decorator
     
     def post(self, path: str, **kwargs):
         """Decorator for POST routes."""
         def decorator(func: Callable):
-            return self.add_route(path, func, methods=["POST"], **kwargs)
+            filtered_kwargs = self._filter_starlette_kwargs(kwargs)
+            return self.add_route(path, func, methods=["POST"], **filtered_kwargs)
         return decorator
     
     def put(self, path: str, **kwargs):
         """Decorator for PUT routes."""
         def decorator(func: Callable):
-            return self.add_route(path, func, methods=["PUT"], **kwargs)
+            filtered_kwargs = self._filter_starlette_kwargs(kwargs)
+            return self.add_route(path, func, methods=["PUT"], **filtered_kwargs)
         return decorator
     
     def delete(self, path: str, **kwargs):
         """Decorator for DELETE routes."""
         def decorator(func: Callable):
-            return self.add_route(path, func, methods=["DELETE"], **kwargs)
+            filtered_kwargs = self._filter_starlette_kwargs(kwargs)
+            return self.add_route(path, func, methods=["DELETE"], **filtered_kwargs)
         return decorator
     
     def patch(self, path: str, **kwargs):
         """Decorator for PATCH routes."""
         def decorator(func: Callable):
-            return self.add_route(path, func, methods=["PATCH"], **kwargs)
+            filtered_kwargs = self._filter_starlette_kwargs(kwargs)
+            return self.add_route(path, func, methods=["PATCH"], **filtered_kwargs)
         return decorator
 
 
@@ -146,3 +170,4 @@ async def __call__(self, request: Request) -> str:
                 detail="Invalid authentication scheme"
             )
         return token
+
diff --git a/src/raystack/contrib/admin/__init__.py b/src/raystack/contrib/admin/__init__.py
@@ -1,10 +1,18 @@
-from raystack.compat import APIRouter
+from raystack.compat import APIRouter, RedirectResponse, Request
 
 from .urls import router as urls_router
 
 from raystack.middlewares import PermissionMiddleware
 
 
 router = APIRouter()
+
+# Add /admin redirect BEFORE mounting urls_router
+# This ensures it's checked before mount("/admin", ...) intercepts the request
+@router.get("/admin")
+async def admin_redirect(request: Request):
+    """Redirect /admin to /admin/"""
+    return RedirectResponse(url="/admin/", status_code=301)
+
 # router.include_router(urls_router, prefix="/admin", include_in_schema=False)
 router.include_router(urls_router, prefix="/admin", tags=["restricted"])
diff --git a/src/raystack/contrib/openapi.py b/src/raystack/contrib/openapi.py

Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-from fastapi import APIRouter`
	`1`	`+from raystack.compat import APIRouter`
`2`	`2`
`3`	`3`	`from .api import router as api_router`
`4`	`4`	`from .urls import router as urls_router`
Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-from fastapi import APIRouter, Request`
	`1`	`+from raystack.compat import APIRouter, Request`
`2`	`2`
`3`	`3`
`4`	`4`	`router = APIRouter()`
Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-from fastapi import Depends`
	`1`	`+from raystack.compat import Depends`
`2`	`2`	`from sqlalchemy.ext.asyncio import AsyncSession`
`3`	`3`
`4`	`4`	`# Use framework functionality for database operations`