Routing & Response Wrapping

ZodiacCore enhances FastAPI's routing system to provide automatic response standardization. By using APIRouter, you ensure that every endpoint returns a consistent JSON structure without manual boilerplate.

1. The Zodiac APIRouter

The APIRouter in ZodiacCore is a drop-in replacement for fastapi.APIRouter. It uses a custom ZodiacRoute class that intercepts outgoing data and wraps it.

Automatic Wrapping

When you return a dictionary, a Pydantic model, or a list from your route, Zodiac automatically wraps it in a Response model:

from zodiac_core.routing import APIRouter

router = APIRouter()

@router.get("/status")
async def get_status():
    return {"status": "online"}

Resulting JSON:

{
  "code": 0,
  "message": "Success",
  "data": {
    "status": "online"
  }
}

2. Standard Response Structure

All Zodiac responses follow this schema:

Field	Type	Description
`code`	`int`	Business status code (0 for success).
`message`	`string`	A brief description of the result.
`data`	`any`	The actual payload (result of your function).

Manual Responses

If you need to return a non-standard response (e.g., a FileResponse or a custom status code), you can still return raw FastAPI Response objects or Zodiac's Response class. If the return type is already a Response, Zodiac will not wrap it again.

from zodiac_core.response import response_ok

@router.get("/custom")
async def manual():
    return response_ok(message="Custom success", data={"id": 1})

3. OpenAPI Integration

ZodiacCore's APIRouter dynamically generates Pydantic models for your responses. This means your Swagger UI (/docs) will correctly display the wrapped structure, including the code, message, and data fields, mapped to your specific return type.

4. API Reference

Routing Utilities

`APIRouter`

Bases: APIRouter

Zodiac-enhanced APIRouter that uses ZodiacRoute by default.

All routes registered via this router will automatically: - Wrap response_model with Response[T] for OpenAPI docs - Wrap endpoint return values with Response structure

Source code in zodiac_core/routing.py

class APIRouter(FastAPIRouter):
    """
    Zodiac-enhanced APIRouter that uses ZodiacRoute by default.

    All routes registered via this router will automatically:
    - Wrap response_model with Response[T] for OpenAPI docs
    - Wrap endpoint return values with Response structure
    """

    def __init__(self, *args, **kwargs):
        kwargs.setdefault("route_class", ZodiacRoute)
        super().__init__(*args, **kwargs)

`ZodiacRoute`

Bases: APIRoute

Custom APIRoute that automatically wraps response models and endpoint returns with the standard Response[T] structure.

Source code in zodiac_core/routing.py

class ZodiacRoute(APIRoute):
    """
    Custom APIRoute that automatically wraps response models and endpoint returns
    with the standard Response[T] structure.
    """

    def __init__(
        self,
        path: str,
        endpoint: Callable[..., Any],
        *,
        response_model: Any = None,
        responses: Optional[Dict[Union[int, str], Dict[str, Any]]] = None,
        **kwargs,
    ) -> None:
        # Resolve FastAPI's DefaultPlaceholder
        if isinstance(response_model, DefaultPlaceholder):
            response_model = response_model.value

        # 1. Wrap main response model (default to Any if missing)
        if self._should_wrap(response_model):
            response_model = self._wrap_response_model(response_model or Any)

        # 2. Wrap additional responses (e.g. 400, 404 models)
        # Copy to avoid mutating caller's dict
        if responses:
            responses = {code: {**res_dict} for code, res_dict in responses.items()}
            for res in responses.values():
                if "model" in res and self._should_wrap(res["model"]):
                    res["model"] = self._wrap_response_model(res["model"])

        # 3. Wrap endpoint to auto-wrap return values
        endpoint = self._wrap_endpoint(endpoint)

        super().__init__(
            path,
            endpoint,
            response_model=response_model,
            responses=responses,
            **kwargs,
        )

    @staticmethod
    def _should_wrap(model: Any) -> bool:
        """Check if a model needs to be wrapped with Response[T]."""
        if model is Any or model is None:
            return True
        origin = get_origin(model)
        if origin is Response:
            return False
        try:
            if isinstance(model, type) and issubclass(model, Response):
                return False
        except TypeError:
            pass
        return True

    @staticmethod
    def _wrap_response_model(model: Any) -> type[Response]:
        """Wrap a model type with Response[T] using Pydantic's native generics."""
        return Response[model]

    @staticmethod
    def _maybe_wrap_result(result: Any) -> Any:
        """Wrap result in Response if not already a Response type."""
        if isinstance(result, (Response, FastAPIResponse)):
            return result
        return Response(data=result)

    @staticmethod
    def _wrap_endpoint(endpoint: Callable) -> Callable:
        """Wrap endpoint to automatically wrap return values in Response."""

        @wraps(endpoint)
        async def async_wrapper(*args, **kwargs):
            result = await endpoint(*args, **kwargs)
            return ZodiacRoute._maybe_wrap_result(result)

        @wraps(endpoint)
        def sync_wrapper(*args, **kwargs):
            result = endpoint(*args, **kwargs)
            return ZodiacRoute._maybe_wrap_result(result)

        return async_wrapper if inspect.iscoroutinefunction(endpoint) else sync_wrapper