fastapi-mongo-base 1.3.5__tar.gz → 1.3.7__tar.gz

{fastapi_mongo_base-1.3.5/src/fastapi_mongo_base.egg-info → fastapi_mongo_base-1.3.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fastapi-mongo-base
-Version: 1.3.5
+Version: 1.3.7
 Summary: A simple boilerplate application, including models and schemas and abstract router, for FastAPI with MongoDB
 Author-email: Mahdi Kiani <mahdikiany@gmail.com>
 Maintainer-email: Mahdi Kiani <mahdikiany@gmail.com>

{fastapi_mongo_base-1.3.5 → fastapi_mongo_base-1.3.7}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "fastapi-mongo-base"
-version = "1.3.5"
+version = "1.3.7"
 description = "A simple boilerplate application, including models and schemas and abstract router, for FastAPI with MongoDB"
 readme = "README.md"
 requires-python = ">=3.10"

{fastapi_mongo_base-1.3.5 → fastapi_mongo_base-1.3.7}/src/fastapi_mongo_base/core/app_factory.py

@@ -12,6 +12,7 @@ from fastapi.responses import RedirectResponse
 from fastapi.staticfiles import StaticFiles
 
 from . import config, db, exceptions
+from .error_responses import COMMON_ERROR_RESPONSES, setup_openapi_errors
 
 
 def health(request: fastapi.Request) -> dict[str, str]:
@@ -258,7 +259,10 @@ def create_app(
         license_info=license_info,
     )
 
-    app = fastapi.FastAPI(**data)
+    app = fastapi.FastAPI(
+        **data,
+        responses=kwargs.pop("responses", COMMON_ERROR_RESPONSES),
+    )
 
     app = configure_app(
         app=app,
@@ -356,4 +360,6 @@ def configure_app(
             name="coverage",
         )
 
+    setup_openapi_errors(app)
+
     return app

fastapi_mongo_base-1.3.7/src/fastapi_mongo_base/core/error_responses.py

@@ -0,0 +1,137 @@
+"""OpenAPI error response schemas aligned with exception handlers."""
+
+from typing import Any
+
+import fastapi
+from fastapi.openapi.utils import get_openapi
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class APIErrorResponseModel(BaseModel):
+    """Structured error response for BaseHTTPException handlers."""
+
+    model_config = ConfigDict(extra="allow")
+
+    message: dict[str, str]
+    error_code: str
+    detail: str | None = None
+
+
+class ValidationReason(BaseModel):
+    """Single field validation failure."""
+
+    model_config = ConfigDict(extra="allow")
+
+    field: str
+    type: str | None = None
+    msg: str | None = None
+    input: Any = None
+    ctx: dict[str, Any] | None = None
+
+
+class ValidationErrorResponseModel(BaseModel):
+    """Structured validation error response."""
+
+    message: dict[str, str]
+    error_code: str = "validation_error"
+    detail: None = None
+    reasons: list[ValidationReason] = Field(default_factory=list)
+
+
+class InternalErrorResponseModel(BaseModel):
+    """Fallback response for unhandled exceptions."""
+
+    message: str
+    error: str = "Exception"
+
+
+COMMON_ERROR_RESPONSES: dict[int, dict[str, Any]] = {
+    400: {
+        "model": APIErrorResponseModel,
+        "description": "Bad request",
+    },
+    401: {
+        "model": APIErrorResponseModel,
+        "description": "Unauthorized",
+    },
+    402: {
+        "model": APIErrorResponseModel,
+        "description": "Payment required",
+    },
+    403: {
+        "model": APIErrorResponseModel,
+        "description": "Forbidden",
+    },
+    404: {
+        "model": APIErrorResponseModel,
+        "description": "Not found",
+    },
+    409: {
+        "model": APIErrorResponseModel,
+        "description": "Conflict",
+    },
+    410: {
+        "model": APIErrorResponseModel,
+        "description": "Gone",
+    },
+    422: {
+        "model": ValidationErrorResponseModel,
+        "description": "Validation error",
+    },
+    423: {
+        "model": APIErrorResponseModel,
+        "description": "Locked",
+    },
+    500: {
+        "model": APIErrorResponseModel,
+        "description": "Internal server error",
+    },
+}
+
+
+def _patch_validation_responses(schema: dict[str, Any]) -> None:
+    validation_ref = {
+        "$ref": "#/components/schemas/ValidationErrorResponseModel"
+    }
+    for path_item in schema.get("paths", {}).values():
+        for operation in path_item.values():
+            if not isinstance(operation, dict):
+                continue
+            responses = operation.get("responses")
+            if not isinstance(responses, dict) or "422" not in responses:
+                continue
+            responses["422"] = {
+                "description": "Validation error",
+                "content": {
+                    "application/json": {
+                        "schema": validation_ref,
+                    },
+                },
+            }
+
+
+def setup_openapi_errors(app: fastapi.FastAPI) -> None:
+    """
+    Replace default FastAPI validation error schemas in OpenAPI.
+
+    Args:
+        app: FastAPI application instance.
+
+    """
+
+    def custom_openapi() -> dict[str, Any]:
+        if app.openapi_schema:
+            return app.openapi_schema
+
+        schema = get_openapi(
+            title=app.title,
+            version=app.version,
+            openapi_version=app.openapi_version,
+            description=app.description,
+            routes=app.routes,
+        )
+        _patch_validation_responses(schema)
+        app.openapi_schema = schema
+        return app.openapi_schema
+
+    app.openapi = custom_openapi

{fastapi_mongo_base-1.3.5 → fastapi_mongo_base-1.3.7}/src/fastapi_mongo_base/core/exceptions.py

@@ -15,6 +15,13 @@ from fastapi.exceptions import (
 from fastapi.responses import JSONResponse
 from pydantic import ValidationError
 
+from fastapi_mongo_base.core.error_responses import (
+    APIErrorResponseModel,
+    InternalErrorResponseModel,
+    ValidationErrorResponseModel,
+    ValidationReason,
+)
+
 try:
     from usso.integrations.fastapi import (
         EXCEPTION_HANDLERS as usso_exception_handler,  # noqa: N811
@@ -110,40 +117,75 @@ def base_http_exception_handler(
     else:
         message = exc.message
 
-    return JSONResponse(
-        status_code=exc.status_code,
-        content={
-            "message": message,
-            "error_code": exc.error_code,
-            "detail": exc.detail,
-            **exc.data,
-        },
-    )
+    content = APIErrorResponseModel(
+        message=message,
+        error_code=exc.error_code,
+        detail=exc.detail,
+        **exc.data,
+    ).model_dump()
+    return JSONResponse(status_code=exc.status_code, content=content)
+
+
+def _resolve_validation_message(request: Request) -> dict[str, str]:
+    message = {
+        "en": "Validation error",
+        "fa": "اطلاعات وارد شده صحیح نیست",
+    }
+    if request.headers.get("accept-language"):
+        locales = request.headers.get("accept-language").split(",")
+        filtered_message = {}
+        for locale in locales:
+            lang = locale.split("-")[0]
+            if lang in message:
+                filtered_message[lang] = message[lang]
+        return filtered_message or message
+    return message
+
+
+def _format_validation_reasons(errors: list[dict]) -> list[dict]:
+    reasons_by_field: dict[str, dict] = {}
+    for error in json.loads(json_advanced.dumps(errors)):
+        loc = error.pop("loc", ())
+        field = str(loc[-1]) if loc else "unknown"
+        error.pop("url", None)
+        error["field"] = field
+        reasons_by_field.setdefault(field, error)
+    return list(reasons_by_field.values())
+
+
+def _validation_error_response(
+    request: Request,
+    errors: list[dict],
+    status_code: int = 422,
+) -> JSONResponse:
+    content = ValidationErrorResponseModel(
+        message=_resolve_validation_message(request),
+        reasons=[
+            ValidationReason(**reason)
+            for reason in _format_validation_reasons(errors)
+        ],
+    ).model_dump()
+    return JSONResponse(status_code=status_code, content=content)
 
 
 def pydantic_exception_handler(
-    request: Request, exc: ValidationError
+    request: Request, exc: RequestValidationError | ResponseValidationError
 ) -> JSONResponse:
     """
     Handle Pydantic validation errors and return JSON response.
 
     Args:
         request: FastAPI request object.
-        exc: ValidationError instance.
+        exc: RequestValidationError or ResponseValidationError instance.
 
     Returns:
         JSONResponse with validation error details.
 
     """
     logging.debug("pydantic_exception_handler: %s\n%s", request.url, exc)
-    return JSONResponse(
-        status_code=500,
-        content={
-            "message": str(exc),
-            "error": "Exception",
-            "errors": json.loads(json_advanced.dumps(exc.errors())),
-        },
-    )
+
+    status_code = 500 if isinstance(exc, ResponseValidationError) else 422
+    return _validation_error_response(request, exc.errors(), status_code)
 
 
 async def request_validation_exception_handler(
@@ -185,11 +227,7 @@ async def request_validation_exception_handler(
         dict(request.headers),
     )
 
-    from fastapi.exception_handlers import (
-        request_validation_exception_handler as default_handler,
-    )
-
-    return await default_handler(request, exc)
+    return _validation_error_response(request, exc.errors())
 
 
 def mongodb_exception_handler(
@@ -253,10 +291,8 @@ def general_exception_handler(
     except ImportError:
         pass
 
-    return JSONResponse(
-        status_code=500,
-        content={"message": str(exc), "error": "Exception"},
-    )
+    content = InternalErrorResponseModel(message=str(exc)).model_dump()
+    return JSONResponse(status_code=500, content=content)
 
 
 # A dictionary for dynamic registration

{fastapi_mongo_base-1.3.5 → fastapi_mongo_base-1.3.7}/src/fastapi_mongo_base/routes.py

@@ -11,6 +11,7 @@ from fastapi import APIRouter, BackgroundTasks, Query, Request
 from pydantic import BaseModel
 
 from .core.config import Settings
+from .core.error_responses import COMMON_ERROR_RESPONSES
 from .core.exceptions import BaseHTTPException
 from .models import BaseEntity
 from .schemas import BaseEntitySchema, PaginatedResponse
@@ -90,9 +91,13 @@ class AbstractBaseRouter(metaclass=singleton.Singleton):
         if tags is None:
             tags = [self.model.__name__]
 
-        self.router = APIRouter(
-            prefix=prefix, tags=cast(list[str | Enum], tags), **kwargs
-        )
+        router_kwargs = {
+            "prefix": prefix,
+            "tags": cast(list[str | Enum], tags),
+            "responses": kwargs.pop("responses", COMMON_ERROR_RESPONSES),
+            **kwargs,
+        }
+        self.router = APIRouter(**router_kwargs)
 
         self.config_schemas(self.schema, **kwargs)
         self.config_routes(**kwargs)

{fastapi_mongo_base-1.3.5 → fastapi_mongo_base-1.3.7}/src/fastapi_mongo_base/utils/usso_routes.py

@@ -188,7 +188,7 @@ class AbstractUSSORouterBase(AbstractBaseRouter):
         if item is None:
             raise exceptions.BaseHTTPException(
                 status_code=404,
-                error="item_not_found",
+                error_code="item_not_found",
                 message={
                     "en": f"{self.model.__name__.capitalize()} not found"
                 },
@@ -223,7 +223,7 @@ class AbstractUSSORouterBase(AbstractBaseRouter):
         if filters.get("__deny__"):
             raise exceptions.BaseHTTPException(
                 status_code=403,
-                error="forbidden",
+                error_code="forbidden",
                 message={
                     "en": "You are not authorized to access this resource"
                 },
@@ -448,7 +448,7 @@ class AbstractOwnedUSSORouter(AbstractUSSORouterBase):
         ):
             raise exceptions.BaseHTTPException(
                 status_code=400,
-                error="workspace_required",
+                error_code="workspace_required",
                 message={
                     "en": "User must belong to a workspace for this resource"
                 },

{fastapi_mongo_base-1.3.5 → fastapi_mongo_base-1.3.7/src/fastapi_mongo_base.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fastapi-mongo-base
-Version: 1.3.5
+Version: 1.3.7
 Summary: A simple boilerplate application, including models and schemas and abstract router, for FastAPI with MongoDB
 Author-email: Mahdi Kiani <mahdikiany@gmail.com>
 Maintainer-email: Mahdi Kiani <mahdikiany@gmail.com>

{fastapi_mongo_base-1.3.5 → fastapi_mongo_base-1.3.7}/src/fastapi_mongo_base.egg-info/SOURCES.txt

@@ -33,6 +33,7 @@ src/fastapi_mongo_base/core/app_factory.py
 src/fastapi_mongo_base/core/config.py
 src/fastapi_mongo_base/core/db.py
 src/fastapi_mongo_base/core/enums.py
+src/fastapi_mongo_base/core/error_responses.py
 src/fastapi_mongo_base/core/exceptions.py
 src/fastapi_mongo_base/core/errors/mongodb_errors.py
 src/fastapi_mongo_base/core/errors/resource_errors.py
@@ -46,6 +47,7 @@ tests/conftest.py
 tests/test_apis.py
 tests/test_app.py
 tests/test_mongodb_errors.py
+tests/test_openapi_errors.py
 tests/test_resource_errors.py
 tests/app/__init__.py
 tests/app/main.py

fastapi_mongo_base-1.3.7/tests/test_openapi_errors.py

@@ -0,0 +1,116 @@
+"""Tests for OpenAPI error response schemas."""
+
+from fastapi.testclient import TestClient
+
+from fastapi_mongo_base.core.error_responses import (
+    APIErrorResponseModel,
+    ValidationErrorResponseModel,
+)
+from fastapi_mongo_base.core.exceptions import BaseHTTPException
+
+from .app.server import app as fastapi_app
+
+
+def test_openapi_documents_error_schemas() -> None:
+    """OpenAPI should document custom error response schemas."""
+    schema = fastapi_app.openapi()
+
+    assert "APIErrorResponseModel" in schema["components"]["schemas"]
+    assert "ValidationErrorResponseModel" in schema["components"]["schemas"]
+
+    list_get = schema["paths"]["/test"]["get"]["responses"]
+    assert "404" in list_get
+    assert (
+        list_get["404"]["content"]["application/json"]["schema"]["$ref"]
+        == "#/components/schemas/APIErrorResponseModel"
+    )
+
+    create_post = schema["paths"]["/test"]["post"]["responses"]
+    assert "422" in create_post
+    assert (
+        create_post["422"]["content"]["application/json"]["schema"]["$ref"]
+        == "#/components/schemas/ValidationErrorResponseModel"
+    )
+
+
+def test_openapi_error_models_match_handler_output() -> None:
+    """Documented schemas should include fields returned by handlers."""
+    api_schema = APIErrorResponseModel.model_json_schema()
+    assert "message" in api_schema["properties"]
+    assert "error_code" in api_schema["properties"]
+    assert "detail" in api_schema["properties"]
+
+    validation_schema = ValidationErrorResponseModel.model_json_schema()
+    assert "reasons" in validation_schema["properties"]
+    assert validation_schema["properties"]["error_code"]["default"] == (
+        "validation_error"
+    )
+
+
+def test_runtime_validation_error_matches_openapi_schema() -> None:
+    """Validation handler response should match documented error shape."""
+    client = TestClient(fastapi_app)
+    response = client.post("/test", json={})
+
+    assert response.status_code == 422
+    body = response.json()
+    assert body["error_code"] == "validation_error"
+    assert "message" in body
+    assert "reasons" in body
+    assert isinstance(body["reasons"], list)
+
+
+def test_runtime_base_http_exception_matches_openapi_schema() -> None:
+    """BaseHTTPException handler response should match documented shape."""
+    from starlette.requests import Request
+
+    from fastapi_mongo_base.core.exceptions import base_http_exception_handler
+
+    request = Request({
+        "type": "http",
+        "headers": [],
+        "method": "GET",
+        "path": "/test/not-a-real-uid",
+    })
+    exc = BaseHTTPException(
+        status_code=404,
+        error_code="item_not_found",
+        message={"en": "Testentity not found"},
+    )
+
+    response = base_http_exception_handler(request, exc)
+    body = response.body.decode()
+
+    assert response.status_code == 404
+    assert "item_not_found" in body
+    assert "Testentity not found" in body
+
+
+def test_custom_route_documents_api_error_response() -> None:
+    """App-level responses should document APIErrorResponseModel on routes."""
+    from fastapi import FastAPI
+
+    from fastapi_mongo_base.core.app_factory import setup_exception_handlers
+    from fastapi_mongo_base.core.error_responses import (
+        COMMON_ERROR_RESPONSES,
+        setup_openapi_errors,
+    )
+
+    app = FastAPI(responses=COMMON_ERROR_RESPONSES)
+    setup_exception_handlers(app=app)
+    setup_openapi_errors(app)
+
+    @app.get("/missing")
+    def raise_not_found() -> None:
+        raise BaseHTTPException(
+            status_code=404,
+            error_code="item_not_found",
+            message={"en": "Item not found"},
+        )
+
+    schema = app.openapi()
+    responses = schema["paths"]["/missing"]["get"]["responses"]
+    assert (
+        responses["404"]["content"]["application/json"]["schema"]["$ref"]
+        == "#/components/schemas/APIErrorResponseModel"
+    )