Added use_aliases

Author: mr-fatalyst

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -15,7 +15,7 @@ body:
     attributes:
       label: Environment
       description: Describe your environment (Python version, OS, FastOpenAPI version, framework used, etc.)
-      placeholder: Python 3.11, FastOpenAPI 0.5.0, Ubuntu 22.04, Flask 2.2
+      placeholder: Python 3.11, FastOpenAPI 0.6.0, Ubuntu 22.04, Flask 2.2
     validations:
       required: true
 

CHANGELOG.md

@@ -4,6 +4,18 @@ All notable changes to FastOpenAPI are documented in this file.
 
 FastOpenAPI follows the [Keep a Changelog](https://keepachangelog.com/en/1.0.0/) format.
 
+## [0.6.0] – 2025‑04‑16
+
+### Added
+- The `use_aliases` parameter was added to the `BaseRouter` constructor. Default is `True`. To preserve the previous behavior (without using aliases from Pydantic), set `use_aliases=False`. 
+
+### Changed
+- The `_serialize_response method` is now an instance method (was a `@staticmethod`) — to support `use_aliases`.
+- The `_get_model_schema` method was temporarily changed from a `@classmethod` to a regular method — for consistent behavior with `use_aliases`.
+
+### Deprecated
+- `use_aliases` is deprecated and will be removed in version 0.7.0.
+
 ## [0.5.0] - 2025-04-13
 
 ### Added

docs/en/docs/changelog.md

@@ -2,6 +2,19 @@
 
 All notable changes to FastOpenAPI will be documented in this file.
 
+## [0.6.0] – 2025‑04‑16
+
+### Added
+- The `use_aliases` parameter was added to the `BaseRouter` constructor. Default is `True`. To preserve the previous behavior (without using aliases from Pydantic), set `use_aliases=False`. 
+
+### Changed
+- The `_serialize_response method` is now an instance method (was a `@staticmethod`) — to support `use_aliases`.
+- The `_get_model_schema` method was temporarily changed from a `@classmethod` to a regular method — for consistent behavior with `use_aliases`.
+
+### Deprecated
+- `use_aliases` is deprecated and will be removed in version 0.7.0.
+
+
 ## [0.5.0] - 2025-04-13
 
 ### Added

fastopenapi/__init__.py

@@ -1 +1 @@
-__version__ = "0.5.0"
+__version__ = "0.6.0"

fastopenapi/base_router.py

@@ -1,6 +1,7 @@
 import inspect
 import re
 import typing
+import warnings
 from collections.abc import Callable
 from http import HTTPStatus
 from typing import Any, ClassVar
@@ -43,6 +44,7 @@ class BaseRouter:
     - title: Title of the API documentation (defaults to "My App").
     - version: Version of the API (defaults to "0.1.0").
     - description: Description of the API
+    - use_aliases: Temporary argument to maintain backward compatibility
     (included in OpenAPI info, default "API documentation").
 
     The BaseRouter allows defining routes using decorator methods (get, post, etc.).
@@ -63,6 +65,7 @@ def __init__(
         title: str = "My App",
         version: str = "0.1.0",
         description: str = "API documentation",
+        use_aliases: bool = True,
     ):
         self.app = app
         self.docs_url = docs_url
@@ -74,6 +77,15 @@ def __init__(
         self.description = description
         self._routes: list[tuple[str, str, Callable]] = []
         self._openapi_schema = None
+        self.use_aliases = use_aliases
+        # TODO Remove use_aliases in 0.7.0
+        if not use_aliases:
+            warnings.warn(
+                "Setting use_aliases=False is deprecated. "
+                "It will be removed in version 0.7.0",
+                FutureWarning,
+                stacklevel=2,
+            )
         if self.app is not None:
             if self.docs_url and self.redoc_url and self.openapi_url:
                 self._register_docs_endpoints()
@@ -225,8 +237,9 @@ def _build_parameters_and_body(
                 param.annotation, BaseModel
             ):
                 if http_method.upper() == "GET":
+                    # TODO Remove use_aliases in 0.7.0
                     model_schema = param.annotation.model_json_schema(
-                        mode="serialization"
+                        mode="serialization" if self.use_aliases else "validation"
                     )
                     required_fields = model_schema.get("required", [])
                     properties = model_schema.get("properties", {})
@@ -334,31 +347,32 @@ def _register_docs_endpoints(self):
         """
         raise NotImplementedError
 
-    @staticmethod
-    def _serialize_response(result: Any) -> Any:
+    def _serialize_response(self, result: Any) -> Any:
         from pydantic import BaseModel
 
         if isinstance(result, BaseModel):
-            return result.model_dump(by_alias=True)
+            # TODO Remove use_aliases in 0.7.0
+            return result.model_dump(by_alias=self.use_aliases)
         if isinstance(result, list):
-            return [BaseRouter._serialize_response(item) for item in result]
+            return [self._serialize_response(item) for item in result]
         if isinstance(result, dict):
-            return {k: BaseRouter._serialize_response(v) for k, v in result.items()}
+            return {k: self._serialize_response(v) for k, v in result.items()}
         return result
 
-    @classmethod
-    def _get_model_schema(cls, model: type[BaseModel], definitions: dict) -> dict:
+    def _get_model_schema(self, model: type[BaseModel], definitions: dict) -> dict:
         """
         Get the OpenAPI schema for a Pydantic model, with caching for better performance
         """
         model_name = model.__name__
         cache_key = f"{model.__module__}.{model_name}"
 
         # Check if the schema is already in the class-level cache
-        if cache_key not in cls._model_schema_cache:
+        if cache_key not in self._model_schema_cache:
             # Generate the schema if it's not in the cache
+            # TODO Remove use_aliases in 0.7.0
             model_schema = model.model_json_schema(
-                mode="serialization", ref_template="#/components/schemas/{model}"
+                mode="serialization" if self.use_aliases else "validation",
+                ref_template="#/components/schemas/{model}",
             )
 
             # Process and store nested definitions
@@ -368,11 +382,11 @@ def _get_model_schema(cls, model: type[BaseModel], definitions: dict) -> dict:
                     del model_schema[key]
 
             # Add schema to the cache
-            cls._model_schema_cache[cache_key] = model_schema
+            self._model_schema_cache[cache_key] = model_schema
 
         # Make sure the schema is in the definitions dictionary
         if model_name not in definitions:
-            definitions[model_name] = cls._model_schema_cache[cache_key]
+            definitions[model_name] = self._model_schema_cache[cache_key]
 
         return {"$ref": f"#/components/schemas/{model_name}"}
 

tests/test_base_router.py

@@ -76,6 +76,12 @@ def test_init_without_app(self):
         assert self.router_no_app._routes == []
         assert self.router_no_app._openapi_schema is None
 
+    def test_use_aliases_deprecation_warning(self):
+        with pytest.warns(FutureWarning) as record:
+            BaseRouter(use_aliases=False)
+        msg = str(record[0].message)
+        assert "will be removed in version 0.7.0" in msg
+
     def test_add_route(self):
         # Test adding a route to the router
         def test_endpoint():
@@ -420,7 +426,7 @@ def new_endpoint():
     def test_serialize_response_with_pydantic_model(self):
         # Test serializing a Pydantic model response
         model = ResponseModel(id=1, message="test")
-        result = BaseRouter._serialize_response(model)
+        result = BaseRouter()._serialize_response(model)
 
         assert isinstance(result, dict)
         assert result["id"] == 1
@@ -432,7 +438,7 @@ def test_serialize_response_with_list(self):
             ResponseModel(id=1, message="test1"),
             ResponseModel(id=2, message="test2"),
         ]
-        result = BaseRouter._serialize_response(models)
+        result = BaseRouter()._serialize_response(models)
 
         assert isinstance(result, list)
         assert len(result) == 2
@@ -445,7 +451,7 @@ def test_serialize_response_with_dict(self):
             "item1": ResponseModel(id=1, message="test1"),
             "item2": ResponseModel(id=2, message="test2"),
         }
-        result = BaseRouter._serialize_response(data)
+        result = BaseRouter()._serialize_response(data)
 
         assert isinstance(result, dict)
         assert len(result) == 2
@@ -454,14 +460,15 @@ def test_serialize_response_with_dict(self):
 
     def test_serialize_response_with_primitive(self):
         # Test serializing primitive values
-        assert BaseRouter._serialize_response(5) == 5
-        assert BaseRouter._serialize_response("test") == "test"
-        assert BaseRouter._serialize_response(True) is True
+        router = BaseRouter()
+        assert router._serialize_response(5) == 5
+        assert router._serialize_response("test") == "test"
+        assert router._serialize_response(True) is True
 
     def test_get_model_schema(self):
         # Test getting Pydantic model schema
         definitions = {}
-        schema = BaseRouter._get_model_schema(TestModel, definitions)
+        schema = BaseRouter()._get_model_schema(TestModel, definitions)
 
         assert "$ref" in schema
         assert schema["$ref"] == "#/components/schemas/TestModel"
@@ -473,7 +480,7 @@ def test_get_model_schema(self):
     def test_get_model_schema_with_nested_models(self):
         # Test getting schema for models with nested models
         definitions = {}
-        schema = BaseRouter._get_model_schema(NestedModel, definitions)
+        schema = BaseRouter()._get_model_schema(NestedModel, definitions)
 
         assert "$ref" in schema
         assert schema["$ref"] == "#/components/schemas/NestedModel"