django-ninja-aio-crud 2.7.0__py3-none-any.whl → 2.8.0__py3-none-any.whl

{django_ninja_aio_crud-2.7.0.dist-info → django_ninja_aio_crud-2.8.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: django-ninja-aio-crud
-Version: 2.7.0
+Version: 2.8.0
 Summary: Django Ninja AIO CRUD - Rest Framework
 Author: Giuseppe Casillo
 Requires-Python: >=3.10, <3.15

{django_ninja_aio_crud-2.7.0.dist-info → django_ninja_aio_crud-2.8.0.dist-info}/RECORD

@@ -1,29 +1,29 @@
-ninja_aio/__init__.py,sha256=FkPurmyPz8Yv7VAiIOZYbFEghPXZ7aeLYX5xBwFSMtk,119
+ninja_aio/__init__.py,sha256=s2uQ_vbFbWOcD6laB1hG40Mv67xvXbSehMTUbkWCcrA,119
 ninja_aio/api.py,sha256=tuC7vdvn7s1GkCnSFy9Kn1zv0glZfYptRQVvo8ZRtGQ,2429
 ninja_aio/auth.py,sha256=4sWdFPjKiQgUL1d_CSGDblVjnY5ptP6LQha6XXdluJA,9157
 ninja_aio/exceptions.py,sha256=_3xFqfFCOfrrMhSA0xbMqgXy8R0UQjhXaExrFvaDAjY,3891
 ninja_aio/parsers.py,sha256=e_4lGCPV7zs-HTqtdJTc8yQD2KPAn9njbL8nF_Mmgkc,153
 ninja_aio/renders.py,sha256=89g46NWUT8nmDG-rG0nxUYbAQWhuXcYKrPh7e1r_Fc4,1735
-ninja_aio/types.py,sha256=nFqWEopm7eoEaHRzbi6EyA9WZ5Cneyd602ilFKypeQI,577
+ninja_aio/types.py,sha256=E3yfXbNKkvLVcr8bvkHTSyIiCRZ4zumzJaXj1aiBi5U,735
 ninja_aio/decorators/__init__.py,sha256=cDDHD_9EI4CP7c5eL1m2mGNl9bR24i8FAkQsT3_RNGM,371
 ninja_aio/decorators/operations.py,sha256=L9yt2ku5oo4CpOLixCADmkcFjLGsWAn-cg-sDcjFhMA,343
 ninja_aio/decorators/views.py,sha256=0RVU4XaM1HvTQ-BOt_NwUtbhwfHau06lh-O8El1LqQk,8139
 ninja_aio/factory/__init__.py,sha256=IdH2z1ZZpv_IqonaDfVo7IsMzkgop6lHqz42RphUYBU,72
 ninja_aio/factory/operations.py,sha256=OgWGqq4WJ4arSQrH9FGAby9kx-HTdS7MOITxHdYMk18,12051
 ninja_aio/helpers/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-ninja_aio/helpers/api.py,sha256=YMzuZ4-ZpUrJBQIabE26gb_GYwsH2rVosWRE95YfdPQ,20775
+ninja_aio/helpers/api.py,sha256=2beyexep-ehgaA_1bV5Yuh3zRDVcRCMkrW94nmfDWEA,20819
 ninja_aio/helpers/query.py,sha256=lzaH-htswoJVRT-W736HGMkpMba1VmN98TBLv5cZx9Q,4549
 ninja_aio/models/__init__.py,sha256=L3UQnQAlKoI3F7jinadL-Nn55hkPvnSRPYW0JtnbWFo,114
-ninja_aio/models/serializers.py,sha256=AlZIkwIiOt-nGBfMDoXu9tJotfzH5L13fv3Rw_4sKUg,35697
+ninja_aio/models/serializers.py,sha256=uviKndPf9HRySup-0t_nULJs-vDLCeGFLtkkQGZvi2E,38142
 ninja_aio/models/utils.py,sha256=P-YfbVyzUfxm_s1BrgSd6Zs0HIGdZ79PU1qM0Ud9-Xs,30492
 ninja_aio/schemas/__init__.py,sha256=iLBwHg0pmL9k_UkIui5Q8QIl_gO4fgxSv2JHxDzqnSI,549
 ninja_aio/schemas/api.py,sha256=-VwXhBRhmMsZLIAmWJ-P7tB5klxXS75eukjabeKKYsc,360
 ninja_aio/schemas/generics.py,sha256=frjJsKJMAdM_NdNKv-9ddZNGxYy5PNzjIRGtuycgr-w,112
-ninja_aio/schemas/helpers.py,sha256=W6IeHi5Tmbjh3FXwDYqjqlLBTVj5uTYq3_JVkNUWayo,7355
+ninja_aio/schemas/helpers.py,sha256=KkbDgT7DwvdeBHZ__wurQQ9A1AIy-toCIL9dCzkTFhM,8350
 ninja_aio/views/__init__.py,sha256=DEzjWA6y3WF0V10nNF8eEurLNEodgxKzyFd09AqVp3s,148
-ninja_aio/views/api.py,sha256=GRtjCvAv7jAp3TxpOirsbMVKpBd8hymSMILdE-JLxvI,21327
+ninja_aio/views/api.py,sha256=l7z-Cg_BUPRi3TAGpO2EppVA2tUAWUftQAn_qOn6XlM,21963
 ninja_aio/views/mixins.py,sha256=Jh6BG8Cs823nurVlODlzCquTxKrLH7Pmo5udPqUGZek,11378
-django_ninja_aio_crud-2.7.0.dist-info/licenses/LICENSE,sha256=yrDAYcm0gRp_Qyzo3GQa4BjYjWRkAhGC8QRva__RYq0,1073
-django_ninja_aio_crud-2.7.0.dist-info/WHEEL,sha256=G2gURzTEtmeR8nrdXUJfNiB3VYVxigPQ-bEQujpNiNs,82
-django_ninja_aio_crud-2.7.0.dist-info/METADATA,sha256=_eQi4SR0xvfnLM6ShB-yvkxffFzUsxNCB39spSHWTOU,9963
-django_ninja_aio_crud-2.7.0.dist-info/RECORD,,
+django_ninja_aio_crud-2.8.0.dist-info/licenses/LICENSE,sha256=yrDAYcm0gRp_Qyzo3GQa4BjYjWRkAhGC8QRva__RYq0,1073
+django_ninja_aio_crud-2.8.0.dist-info/WHEEL,sha256=G2gURzTEtmeR8nrdXUJfNiB3VYVxigPQ-bEQujpNiNs,82
+django_ninja_aio_crud-2.8.0.dist-info/METADATA,sha256=k3VWPUTlkXEe0tZRt7cWWtdA_5i_31gjkUM3t402nBI,9963
+django_ninja_aio_crud-2.8.0.dist-info/RECORD,,

ninja_aio/__init__.py

@@ -1,6 +1,6 @@
 """Django Ninja AIO CRUD - Rest Framework"""
 
-__version__ = "2.7.0"
+__version__ = "2.8.0"
 
 from .api import NinjaAIO
 

ninja_aio/helpers/api.py

@@ -472,7 +472,7 @@ class ManyToManyAPI:
         model = relation.model
         related_name = relation.related_name
         m2m_auth = relation.auth or self.default_auth
-        rel_util = ModelUtil(model)
+        rel_util = ModelUtil(model, serializer_class=relation.serializer_class)
         rel_path = relation.path or rel_util.verbose_name_path_resolver()
         related_schema = relation.related_schema
         m2m_add, m2m_remove, m2m_get = relation.add, relation.remove, relation.get

ninja_aio/models/serializers.py

@@ -1,4 +1,4 @@
-from typing import Any, List, Optional, Union, get_args, get_origin, ForwardRef
+from typing import Any, List, Literal, Optional, Union, get_args, get_origin, ForwardRef
 import warnings
 import sys
 
@@ -15,7 +15,13 @@ from django.db.models.fields.related_descriptors import (
     ForwardOneToOneDescriptor,
 )
 
-from ninja_aio.types import S_TYPES, F_TYPES, SCHEMA_TYPES, ModelSerializerMeta
+from ninja_aio.types import (
+    S_TYPES,
+    F_TYPES,
+    SCHEMA_TYPES,
+    ModelSerializerMeta,
+    SerializerMeta,
+)
 from ninja_aio.schemas.helpers import (
     ModelQuerySetSchema,
     ModelQuerySetExtraSchema,
@@ -98,6 +104,7 @@ class BaseSerializer:
                 module = sys.modules.get(module_path)
                 if module is None:
                     import importlib
+
                     module = importlib.import_module(module_path)
 
                 # Get the serializer class from the module
@@ -136,7 +143,9 @@ class BaseSerializer:
         return serializer_class
 
     @classmethod
-    def _resolve_serializer_reference(cls, serializer_ref: str | type | Any) -> type | Any:
+    def _resolve_serializer_reference(
+        cls, serializer_ref: str | type | Any
+    ) -> type | Any:
         """
         Resolve a serializer reference that may be a string, a class, or a Union of serializers.
 
@@ -217,11 +226,11 @@ class BaseSerializer:
         Schema | Union[Schema, ...] | None
             Union of generated schemas or None if all schemas are None.
         """
-        # Generate schemas for each serializer in the Union
+        # Generate schemas for each serializer in the Union (single call per serializer)
         schemas = tuple(
-            serializer_type.generate_related_s()
+            schema
             for serializer_type in get_args(resolved_union)
-            if serializer_type.generate_related_s() is not None
+            if (schema := serializer_type.generate_related_s()) is not None
         )
 
         if not schemas:
@@ -393,72 +402,100 @@ class BaseSerializer:
         return (field_name, schema | None, None)
 
     @classmethod
-    def get_schema_out_data(cls):
+    def _is_reverse_relation(cls, field_obj) -> bool:
+        """Check if field is a reverse relation (M2M, reverse FK, reverse O2O)."""
+        return isinstance(
+            field_obj,
+            (ManyToManyDescriptor, ReverseManyToOneDescriptor, ReverseOneToOneDescriptor),
+        )
+
+    @classmethod
+    def _is_forward_relation(cls, field_obj) -> bool:
+        """Check if field is a forward relation (FK, O2O)."""
+        return isinstance(
+            field_obj, (ForwardOneToOneDescriptor, ForwardManyToOneDescriptor)
+        )
+
+    @classmethod
+    def _warn_missing_relation_serializer(cls, field_name: str, model) -> None:
+        """Emit warning for reverse relations without explicit serializer mapping."""
+        if (
+            not isinstance(model, ModelSerializerMeta)
+            and not getattr(settings, "NINJA_AIO_TESTING", False)
+        ):
+            warnings.warn(
+                f"{cls.__name__}: reverse relation '{field_name}' is listed in read fields "
+                "but has no entry in relations_serializers; it will be auto-resolved only "
+                "for ModelSerializer relations, otherwise skipped.",
+                UserWarning,
+                stacklevel=3,
+            )
+
+    @classmethod
+    def _process_field(
+        cls,
+        field_name: str,
+        model,
+        relations_serializers: dict,
+    ) -> tuple[str | None, tuple | None, tuple | None]:
+        """
+        Process a single field and determine its classification.
+
+        Returns:
+            (plain_field, reverse_rel, forward_rel) - only one will be non-None
+        """
+        field_obj = getattr(model, field_name)
+
+        if cls._is_reverse_relation(field_obj):
+            if field_name not in relations_serializers:
+                cls._warn_missing_relation_serializer(field_name, model)
+            rel_tuple = cls._build_schema_reverse_rel(field_name, field_obj)
+            return (None, rel_tuple, None)
+
+        if cls._is_forward_relation(field_obj):
+            rel_tuple = cls._build_schema_forward_rel(field_name, field_obj)
+            if rel_tuple is True:
+                return (field_name, None, None)
+            return (None, None, rel_tuple)
+
+        return (field_name, None, None)
+
+    @classmethod
+    def get_schema_out_data(cls, schema_type: Literal["Out", "Detail"] = "Out"):
         """
-        Collect components for 'Out' read schema generation.
-        Returns (fields, reverse_rel_descriptors, excludes, custom_fields_with_forward_relations, optionals).
-        Enforces relation serializers only when provided by subclass via _get_relations_serializers.
+        Collect components for output schema generation (Out or Detail).
+
+        Returns:
+            tuple: (fields, reverse_rels, excludes, customs_with_forward_rels, optionals)
         """
+        if schema_type not in ("Out", "Detail"):
+            raise ValueError("get_schema_out_data only supports 'Out' or 'Detail' types")
+
+        fields_type = "read" if schema_type == "Out" else "detail"
+        model = cls._get_model()
+        relations_serializers = cls._get_relations_serializers() or {}
+
         fields: list[str] = []
         reverse_rels: list[tuple] = []
-        rels: list[tuple] = []
-        relations_serializers = cls._get_relations_serializers() or {}
-        model = cls._get_model()
+        forward_rels: list[tuple] = []
 
-        for f in cls.get_fields("read"):
-            field_obj = getattr(model, f)
-            is_reverse = isinstance(
-                field_obj,
-                (
-                    ManyToManyDescriptor,
-                    ReverseManyToOneDescriptor,
-                    ReverseOneToOneDescriptor,
-                ),
+        for field_name in cls.get_fields(fields_type):
+            plain, reverse, forward = cls._process_field(
+                field_name, model, relations_serializers
             )
-            is_forward = isinstance(
-                field_obj, (ForwardOneToOneDescriptor, ForwardManyToOneDescriptor)
-            )
-
-            # If explicit relation serializers are declared, require mapping presence.
-            if (
-                is_reverse
-                and not isinstance(model, ModelSerializerMeta)
-                and f not in relations_serializers
-                and not getattr(settings, "NINJA_AIO_TESTING", False)
-            ):
-                warnings.warn(
-                    f"{cls.__name__}: reverse relation '{f}' is listed in read fields but has no entry in relations_serializers; "
-                    "it will be auto-resolved only for ModelSerializer relations, otherwise skipped.",
-                    UserWarning,
-                    stacklevel=2,
-                )
-
-            # Reverse relations
-            if is_reverse:
-                rel_tuple = cls._build_schema_reverse_rel(f, field_obj)
-                if rel_tuple:
-                    reverse_rels.append(rel_tuple)
-                continue
-
-            # Forward relations
-            if is_forward:
-                rel_tuple = cls._build_schema_forward_rel(f, field_obj)
-                if rel_tuple is True:
-                    fields.append(f)
-                elif rel_tuple:
-                    rels.append(rel_tuple)
-                # None -> skip entirely
-                continue
-
-            # Plain field
-            fields.append(f)
+            if plain:
+                fields.append(plain)
+            if reverse:
+                reverse_rels.append(reverse)
+            if forward:
+                forward_rels.append(forward)
 
         return (
             fields,
             reverse_rels,
-            cls.get_excluded_fields("read"),
-            cls.get_custom_fields("read") + rels,
-            cls.get_optional_fields("read"),
+            cls.get_excluded_fields(fields_type),
+            cls.get_custom_fields(fields_type) + forward_rels,
+            cls.get_optional_fields(fields_type),
         )
 
     @classmethod
@@ -474,15 +511,16 @@ class BaseSerializer:
         model = cls._get_model()
 
         # Handle special schema types with custom logic
-        if schema_type == "Out":
+        if schema_type == "Out" or schema_type == "Detail":
             fields, reverse_rels, excludes, customs, optionals = (
-                cls.get_schema_out_data()
+                cls.get_schema_out_data(schema_type)
             )
             if not any([fields, reverse_rels, excludes, customs]):
                 return None
+            schema_name = "SchemaOut" if schema_type == "Out" else "DetailSchemaOut"
             return create_schema(
                 model=model,
-                name=f"{model._meta.model_name}SchemaOut",
+                name=f"{model._meta.model_name}{schema_name}",
                 depth=depth,
                 fields=fields,
                 custom_fields=reverse_rels + customs + optionals,
@@ -561,6 +599,11 @@ class BaseSerializer:
         """Generate read (Out) schema."""
         return cls._generate_model_schema("Out", depth)
 
+    @classmethod
+    def generate_detail_s(cls, depth: int = 1) -> Schema:
+        """Generate detail (single object Out) schema."""
+        return cls._generate_model_schema("Detail", depth)
+
     @classmethod
     def generate_create_s(cls) -> Schema:
         """Generate create (In) schema."""
@@ -659,6 +702,26 @@ class ModelSerializer(models.Model, BaseSerializer, metaclass=ModelSerializerMet
         optionals: list[tuple[str, type]] = []
         excludes: list[str] = []
 
+    class DetailSerializer:
+        """Configuration describing detail (single object) read schema.
+
+        Attributes
+        ----------
+        fields : list[str]
+            Explicit model fields to include.
+        excludes : list[str]
+            Fields to force exclude (safety).
+        customs : list[tuple[str, type, Any]]
+            Computed / synthetic output attributes.
+        optionals : list[tuple[str, type]]
+            Optional output fields.
+        """
+
+        fields: list[str] = []
+        customs: list[tuple[str, type, Any]] = []
+        optionals: list[tuple[str, type]] = []
+        excludes: list[str] = []
+
     class UpdateSerializer:
         """Configuration describing update (PATCH/PUT) schema.
 
@@ -684,6 +747,7 @@ class ModelSerializer(models.Model, BaseSerializer, metaclass=ModelSerializerMet
         "create": "CreateSerializer",
         "update": "UpdateSerializer",
         "read": "ReadSerializer",
+        "detail": "DetailSerializer",
     }
 
     @classmethod
@@ -852,7 +916,7 @@ class SchemaModelConfig(Schema):
     customs: Optional[List[tuple[str, type, Any]]] = None
 
 
-class Serializer(BaseSerializer):
+class Serializer(BaseSerializer, metaclass=SerializerMeta):
     """
     Serializer
     ----------
@@ -867,6 +931,7 @@ class Serializer(BaseSerializer):
         "create": "in",
         "update": "update",
         "read": "out",
+        "detail": "detail",
     }
 
     def __init_subclass__(cls, **kwargs):
@@ -884,6 +949,7 @@ class Serializer(BaseSerializer):
         schema_in: Optional[SchemaModelConfig] = None
         schema_out: Optional[SchemaModelConfig] = None
         schema_update: Optional[SchemaModelConfig] = None
+        schema_detail: Optional[SchemaModelConfig] = None
         relations_serializers: dict[str, "Serializer"] = {}
 
     @classmethod
@@ -908,6 +974,8 @@ class Serializer(BaseSerializer):
                 return cls._get_meta_data("schema_out")
             case "update":
                 return cls._get_meta_data("schema_update")
+            case "detail":
+                return cls._get_meta_data("schema_detail")
             case _:
                 return None
 
@@ -1027,7 +1095,12 @@ class Serializer(BaseSerializer):
         dict
             Serialized data.
         """
-        return await self.util.read_s(schema=self.generate_read_s(), instance=instance)
+        schema = (
+            self.generate_read_s()
+            if self.generate_detail_s() is None
+            else self.generate_detail_s()
+        )
+        return await self.util.read_s(schema=schema, instance=instance)
 
     async def models_dump(
         self, instances: models.QuerySet[models.Model]

ninja_aio/schemas/helpers.py

@@ -1,7 +1,7 @@
 from typing import List, Optional, Type
 
 from ninja import Schema
-from ninja_aio.types import ModelSerializerMeta
+from ninja_aio.types import ModelSerializerMeta, SerializerMeta
 from django.db.models import Model
 from pydantic import BaseModel, ConfigDict, model_validator
 
@@ -38,6 +38,10 @@ class M2MRelationSchema(BaseModel):
             Optional explicit schema to represent related objects in responses.
             If `model` is a ModelSerializerMeta, this is auto-derived via `model.generate_related_s()`.
             If `model` is a plain Django model, this must be provided.
+            If `model` is a plain DJango model and this is not provided but serializer_class is provided this last one would be used to generate it.
+        serializer_class (Serializer | None):
+            Optional serializer class associated with the related model. If provided alongside a plain Django model,
+            it can be used to auto-generate the `related_schema`.
         append_slash (bool):
             Whether to append a trailing slash to the generated GET endpoint path. Defaults to False for backward compatibility.
 
@@ -63,6 +67,7 @@ class M2MRelationSchema(BaseModel):
     auth: Optional[list] = None
     filters: Optional[dict[str, tuple]] = None
     related_schema: Optional[Type[Schema]] = None
+    serializer_class: Optional[SerializerMeta] = None
     append_slash: bool = False
 
     model_config = ConfigDict(arbitrary_types_allowed=True)
@@ -70,15 +75,30 @@ class M2MRelationSchema(BaseModel):
     @model_validator(mode="before")
     @classmethod
     def validate_related_schema(cls, data):
-        related_schema = data.get("related_schema")
-        if related_schema is not None:
+        # Early return if related_schema is already provided
+        if data.get("related_schema") is not None:
             return data
+
         model = data.get("model")
-        if not isinstance(model, ModelSerializerMeta):
+        serializer_class = data.get("serializer_class")
+        is_model_serializer = isinstance(model, ModelSerializerMeta)
+
+        # Validate incompatible parameters
+        if is_model_serializer and serializer_class:
+            raise ValueError(
+                "Cannot provide serializer_class when model is a ModelSerializerMeta"
+            )
+
+        # Generate related_schema based on available information
+        if is_model_serializer:
+            data["related_schema"] = model.generate_related_s()
+        elif serializer_class:
+            data["related_schema"] = serializer_class.generate_related_s()
+        else:
             raise ValueError(
-                "related_schema must be provided if model is not a ModelSerializer",
+                "related_schema must be provided if model is not a ModelSerializer"
             )
-        data["related_schema"] = model.generate_related_s()
+
         return data
 
 
@@ -95,6 +115,7 @@ class ModelQuerySetExtraSchema(ModelQuerySetSchema):
         select_related (Optional[list[str]]): List of related fields for select_related optimization.
         prefetch_related (Optional[list[str]]): List of related fields for prefetch_related optimization
     """
+
     scope: str
 
 
@@ -106,6 +127,7 @@ class ObjectQuerySchema(ModelQuerySetSchema):
         select_related (Optional[list[str]]): List of related fields for select_related optimization.
         prefetch_related (Optional[list[str]]): List of related fields for prefetch_related optimization
     """
+
     getters: Optional[dict] = {}
 
 
@@ -117,6 +139,7 @@ class ObjectsQuerySchema(ModelQuerySetSchema):
         select_related (Optional[list[str]]): List of related fields for select_related optimization.
         prefetch_related (Optional[list[str]]): List of related fields for prefetch_related optimization
     """
+
     filters: Optional[dict] = {}
 
 
@@ -129,6 +152,7 @@ class QuerySchema(ModelQuerySetSchema):
         select_related (Optional[list[str]]): List of related fields for select_related optimization.
         prefetch_related (Optional[list[str]]): List of related fields for prefetch_related optimization
     """
+
     filters: Optional[dict] = {}
     getters: Optional[dict] = {}
 
@@ -140,6 +164,7 @@ class QueryUtilBaseScopesSchema(BaseModel):
         READ (str): Scope for read operations.
         QUERYSET_REQUEST (str): Scope for queryset request operations.
     """
+
     READ: str = "read"
     QUERYSET_REQUEST: str = "queryset_request"
 
@@ -163,6 +188,7 @@ class DecoratorsSchema(Schema):
           Consider initializing these in __init__ or using default_factory (if using pydantic/dataclasses)
           to avoid unintended side effects.
     """
+
     list: Optional[List] = []
     retrieve: Optional[List] = []
     create: Optional[List] = []

ninja_aio/types.py

@@ -4,16 +4,21 @@ from joserfc import jwk
 from django.db.models import Model
 from typing import TypeAlias
 
-S_TYPES = Literal["read", "create", "update"]
+S_TYPES = Literal["read", "detail", "create", "update"]
 F_TYPES = Literal["fields", "customs", "optionals", "excludes"]
-SCHEMA_TYPES = Literal["In", "Out", "Patch", "Related"]
+SCHEMA_TYPES = Literal["In", "Out", "Detail", "Patch", "Related"]
 VIEW_TYPES = Literal["list", "retrieve", "create", "update", "delete", "all"]
 JwtKeys: TypeAlias = jwk.RSAKey | jwk.ECKey | jwk.OctKey
 
-class ModelSerializerType(type):
-    def __repr__(self):
-        return self.__name__
 
+class SerializerMeta(type):
+    """Metaclass for serializers - extend with custom behavior as needed."""
+
+    def __repr__(cls):
+        return cls.__name__
+
+
+class ModelSerializerMeta(SerializerMeta, type(Model)):
+    """Metaclass combining SerializerMeta with Django's ModelBase."""
 
-class ModelSerializerMeta(ModelSerializerType, type(Model)):
     pass

ninja_aio/views/api.py

@@ -225,6 +225,7 @@ class APIViewSet(API):
     serializer_class: serializers.Serializer | None = None
     schema_in: Schema | None = None
     schema_out: Schema | None = None
+    schema_detail: Schema | None = None
     schema_update: Schema | None = None
     get_auth: list | None = NOT_SET
     post_auth: list | None = NOT_SET
@@ -262,7 +263,9 @@ class APIViewSet(API):
             if not isinstance(self.model, ModelSerializerMeta)
             else self.model.util
         )
-        self.schema_out, self.schema_in, self.schema_update = self.get_schemas()
+        self.schema_out, self.schema_detail, self.schema_in, self.schema_update = (
+            self.get_schemas()
+        )
         self.path_schema = self._generate_path_schema()
         self.filters_schema = self._generate_filters_schema()
         self.model_verbose_name = (
@@ -365,22 +368,24 @@ class APIViewSet(API):
 
     def get_schemas(self):
         """
-        Compute and return (schema_out, schema_in, schema_update).
+        Compute and return (schema_out, schema_detail, schema_in, schema_update).
 
-        - If model is a ModelSerializer (ModelSerializerMeta), auto-generate read/create/update schemas.
+        - If model is a ModelSerializer (ModelSerializerMeta), auto-generate read/detail/create/update schemas.
         - Otherwise, use existing schemas or generate from serializer_class if provided.
         """
         # ModelSerializer case: prefer explicitly set schemas, otherwise generate from the model
         if isinstance(self.model, ModelSerializerMeta):
             return (
                 self.schema_out or self.model.generate_read_s(),
+                self.schema_detail or self.model.generate_detail_s(),
                 self.schema_in or self.model.generate_create_s(),
                 self.schema_update or self.model.generate_update_s(),
             )
 
         # Non-ModelSerializer: start from provided schemas
-        schema_out, schema_in, schema_update = (
+        schema_out, schema_detail, schema_in, schema_update = (
             self.schema_out,
+            self.schema_detail,
             self.schema_in,
             self.schema_update,
         )
@@ -389,9 +394,10 @@ class APIViewSet(API):
         if self.serializer_class:
             schema_in = schema_in or self.serializer_class.generate_create_s()
             schema_out = schema_out or self.serializer_class.generate_read_s()
+            schema_detail = schema_detail or self.serializer_class.generate_detail_s()
             schema_update = schema_update or self.serializer_class.generate_update_s()
 
-        return (schema_out, schema_in, schema_update)
+        return (schema_out, schema_detail, schema_in, schema_update)
 
     async def query_params_handler(
         self, queryset: QuerySet[ModelSerializer], filters: dict
@@ -456,23 +462,31 @@ class APIViewSet(API):
 
         return list
 
+    def _get_retrieve_schema(self) -> Schema:
+        """
+        Return the schema to use for retrieve endpoint.
+        Uses schema_detail if available, otherwise falls back to schema_out.
+        """
+        return self.schema_detail or self.schema_out
+
     def retrieve_view(self):
         """
         Register retrieve endpoint.
         """
+        retrieve_schema = self._get_retrieve_schema()
 
         @self.router.get(
             self.get_path_retrieve,
             auth=self.get_view_auth(),
             summary=f"Retrieve {self.model_verbose_name}",
             description=self.retrieve_docs,
-            response={200: self.schema_out, self.error_codes: GenericMessageSchema},
+            response={200: retrieve_schema, self.error_codes: GenericMessageSchema},
         )
         @decorate_view(unique_view(self), *self.extra_decorators.retrieve)
         async def retrieve(request: HttpRequest, pk: Path[self.path_schema]):  # type: ignore
             query_data = self._get_query_data()
             return await self.model_util.read_s(
-                self.schema_out,
+                retrieve_schema,
                 request,
                 query_data=QuerySchema(
                     getters={"pk": self._get_pk(pk)}, **query_data.model_dump()