django-ninja-aio-crud 2.7.0__tar.gz → 2.8.0__tar.gz

{django_ninja_aio_crud-2.7.0 → django_ninja_aio_crud-2.8.0}/.github/workflows/docs.yml

@@ -19,6 +19,7 @@ on:
           - "2.5"
           - "2.6"
           - "2.6.1"
+          - "2.7.0"
       make_latest:
         description: 'Set as "latest" and default?'
         type: boolean
@@ -41,6 +42,7 @@ on:
           - "2.5"
           - "2.6"
           - "2.6.1"
+          - "2.7.0"
       delete_confirm:
         description: 'Confirm deletion of the selected version'
         type: boolean

{django_ninja_aio_crud-2.7.0 → django_ninja_aio_crud-2.8.0}/PKG-INFO

@@ -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 → django_ninja_aio_crud-2.8.0}/docs/api/models/model_serializer.md

@@ -145,6 +145,66 @@ class User(ModelSerializer):
 }
 ```
 
+### DetailSerializer
+
+Describes how to build a detail (single object) output schema. Use this when you want the retrieve endpoint to return more fields than the list endpoint.
+
+**Attributes:**
+
+| Attribute   | Type                     | Description                                                                   |
+| ----------- | ------------------------ | ----------------------------------------------------------------------------- |
+| `fields`    | `list[str]`              | Model fields to include in detail view                                        |
+| `excludes`  | `list[str]`              | Fields to exclude from detail view                                            |
+| `customs`   | `list[tuple]`            | Computed fields: `(name, type)` required; `(name, type, default)` optional    |
+| `optionals` | `list[tuple[str, type]]` | Optional output fields                                                        |
+
+**Example:**
+
+```python
+class Article(ModelSerializer):
+    title = models.CharField(max_length=200)
+    summary = models.TextField()
+    content = models.TextField()
+    author = models.ForeignKey(User, on_delete=models.CASCADE)
+    tags = models.ManyToManyField(Tag)
+    view_count = models.IntegerField(default=0)
+
+    class ReadSerializer:
+        # List view: minimal fields for performance
+        fields = ["id", "title", "summary", "author"]
+
+    class DetailSerializer:
+        # Detail view: all fields including expensive relations
+        fields = ["id", "title", "summary", "content", "author", "tags", "view_count"]
+        customs = [
+            ("reading_time", int, lambda obj: len(obj.content.split()) // 200),
+        ]
+```
+
+**Generated Output (List):**
+
+```json
+[
+  {"id": 1, "title": "Getting Started", "summary": "...", "author": {...}},
+  {"id": 2, "title": "Advanced Topics", "summary": "...", "author": {...}}
+]
+```
+
+**Generated Output (Detail):**
+
+```json
+{
+  "id": 1,
+  "title": "Getting Started",
+  "summary": "...",
+  "content": "Full article content here...",
+  "author": {...},
+  "tags": [{"id": 1, "name": "python"}, {"id": 2, "name": "django"}],
+  "view_count": 1234,
+  "reading_time": 5
+}
+```
+
 ### UpdateSerializer
 
 Describes how to build an update (partial/full) input schema.
@@ -194,14 +254,15 @@ class User(ModelSerializer):
 
 ### Auto-Generated Schemas
 
-ModelSerializer automatically generates four schema types:
+ModelSerializer automatically generates five schema types:
 
-| Method                     | Schema Type        | Purpose                        |
-| -------------------------- | ------------------ | ------------------------------ |
-| `generate_create_s()`      | Input ("In")       | POST endpoint payload          |
-| `generate_update_s()`      | Input ("Patch")    | PATCH/PUT endpoint payload     |
-| `generate_read_s(depth=1)` | Output ("Out")     | Response with nested relations |
-| `generate_related_s()`     | Output ("Related") | Compact nested representation  |
+| Method                       | Schema Type        | Purpose                              |
+| ---------------------------- | ------------------ | ------------------------------------ |
+| `generate_create_s()`        | Input ("In")       | POST endpoint payload                |
+| `generate_update_s()`        | Input ("Patch")    | PATCH/PUT endpoint payload           |
+| `generate_read_s(depth=1)`   | Output ("Out")     | List response with nested relations  |
+| `generate_detail_s(depth=1)` | Output ("Detail")  | Single object response (retrieve)    |
+| `generate_related_s()`       | Output ("Related") | Compact nested representation        |
 
 **Example:**
 
@@ -219,6 +280,7 @@ class User(ModelSerializer):
 # Auto-generate schemas
 UserCreateSchema = User.generate_create_s()
 UserReadSchema = User.generate_read_s()
+UserDetailSchema = User.generate_detail_s()  # Returns None if DetailSerializer not defined
 UserUpdateSchema = User.generate_update_s()
 UserRelatedSchema = User.generate_related_s()
 ```

{django_ninja_aio_crud-2.7.0 → django_ninja_aio_crud-2.8.0}/docs/api/models/serializers.md

@@ -37,7 +37,8 @@ Define a Serializer subclass with a nested Meta:
 
 - **model**: Django model class
 - **schema_in**: SchemaModelConfig for create inputs
-- **schema_out**: SchemaModelConfig for read outputs
+- **schema_out**: SchemaModelConfig for read outputs (list endpoint)
+- **schema_detail**: SchemaModelConfig for detail outputs (retrieve endpoint)
 - **schema_update**: SchemaModelConfig for patch/update inputs
 - **relations_serializers**: Mapping of relation field name -> Serializer class, **string reference**, or **Union of serializers** (supports forward/circular dependencies and polymorphic relations)
 
@@ -55,13 +56,37 @@ Generate schemas explicitly using these methods:
 ```python
 # Explicitly generate schemas when needed
 ArticleSerializer.generate_create_s()  # Returns create (In) schema
-ArticleSerializer.generate_read_s()    # Returns read (Out) schema
+ArticleSerializer.generate_read_s()    # Returns read (Out) schema for list endpoint
+ArticleSerializer.generate_detail_s()  # Returns detail (Out) schema for retrieve endpoint
 ArticleSerializer.generate_update_s()  # Returns update (Patch) schema
 ArticleSerializer.generate_related_s() # Returns related (nested) schema
 ```
 
 Schemas support **forward references and circular dependencies** via string references in `relations_serializers`.
 
+### Detail Schema for Retrieve Endpoint
+
+Use `schema_detail` when you want the retrieve endpoint to return more fields than the list endpoint:
+
+```python
+class ArticleSerializer(serializers.Serializer):
+    class Meta:
+        model = models.Article
+        schema_out = serializers.SchemaModelConfig(
+            # List view: minimal fields for performance
+            fields=["id", "title", "summary"]
+        )
+        schema_detail = serializers.SchemaModelConfig(
+            # Detail view: all fields including expensive relations
+            fields=["id", "title", "summary", "content", "author", "tags"],
+            customs=[("reading_time", int, lambda obj: len(obj.content.split()) // 200)]
+        )
+```
+
+When used with `APIViewSet`:
+- **List endpoint** (`GET /articles/`) uses `schema_out`
+- **Retrieve endpoint** (`GET /articles/{pk}`) uses `schema_detail` (falls back to `schema_out` if not defined)
+
 ## Example: simple FK
 
 ```python

{django_ninja_aio_crud-2.7.0 → django_ninja_aio_crud-2.8.0}/docs/api/views/api_view_set.md

@@ -4,13 +4,13 @@
 
 ## Generated CRUD Endpoints
 
-| Method | Path            | Summary        | Response                           |
-| ------ | --------------- | -------------- | ---------------------------------- |
-| POST   | `/{base}/`      | Create Model   | `201 schema_out`                   |
-| GET    | `/{base}/`      | List Models    | `200 List[schema_out]` (paginated) |
-| GET    | `/{base}/{pk}`  | Retrieve Model | `200 schema_out`                   |
-| PATCH  | `/{base}/{pk}/` | Update Model   | `200 schema_out`                   |
-| DELETE | `/{base}/{pk}/` | Delete Model   | `204 No Content`                   |
+| Method | Path            | Summary        | Response                                      |
+| ------ | --------------- | -------------- | --------------------------------------------- |
+| POST   | `/{base}/`      | Create Model   | `201 schema_out`                              |
+| GET    | `/{base}/`      | List Models    | `200 List[schema_out]` (paginated)            |
+| GET    | `/{base}/{pk}`  | Retrieve Model | `200 schema_detail` (or `schema_out` if none) |
+| PATCH  | `/{base}/{pk}/` | Update Model   | `200 schema_out`                              |
+| DELETE | `/{base}/{pk}/` | Delete Model   | `204 No Content`                              |
 
 Notes:
 
@@ -100,7 +100,8 @@ class ArticleViewSet(APIViewSet):
 | `api`                       | `NinjaAPI`                    | —                                                  | API instance (required)                                                 |
 | `serializer_class`          | `Serializer \| None`          | `None`                                             | Serializer class for plain models (alternative to ModelSerializer)      |
 | `schema_in`                 | `Schema \| None`              | `None` (auto)                                      | Create input schema override                                            |
-| `schema_out`                | `Schema \| None`              | `None` (auto)                                      | Read/output schema override                                             |
+| `schema_out`                | `Schema \| None`              | `None` (auto)                                      | List/output schema override                                             |
+| `schema_detail`             | `Schema \| None`              | `None` (auto)                                      | Retrieve/detail schema override (falls back to `schema_out`)            |
 | `schema_update`             | `Schema \| None`              | `None` (auto)                                      | Update input schema override                                            |
 | `pagination_class`          | `type[AsyncPaginationBase]`   | `PageNumberPagination`                             | Pagination strategy                                                     |
 | `query_params`              | `dict[str, tuple[type, ...]]` | `{}`                                               | List endpoint filters definition                                        |
@@ -150,6 +151,7 @@ The transaction behavior is applied by default. Custom decorators can be added v
 If `model` is a subclass of `ModelSerializerMeta`:
 
 - `schema_out` is generated from `ReadSerializer`
+- `schema_detail` is generated from `DetailSerializer` (optional, falls back to `schema_out`)
 - `schema_in` from `CreateSerializer`
 - `schema_update` from `UpdateSerializer`
 
@@ -173,7 +175,42 @@ class ArticleViewSet(APIViewSet):
     serializer_class = ArticleSerializer
 ```
 
-Otherwise provide schemas manually via `schema_in`, `schema_out`, and `schema_update` attributes.
+Otherwise provide schemas manually via `schema_in`, `schema_out`, `schema_detail`, and `schema_update` attributes.
+
+### Detail Schema for Retrieve Endpoint
+
+Use `schema_detail` (or `DetailSerializer` on ModelSerializer) when you want the retrieve endpoint to return more fields than the list endpoint. This is useful for:
+
+- **Performance optimization**: List endpoints return minimal fields, retrieve endpoints include expensive relations
+- **API design**: Clients get a summary in lists and full details on individual requests
+
+```python
+from ninja_aio.models import ModelSerializer
+from django.db import models
+
+class Article(ModelSerializer):
+    title = models.CharField(max_length=200)
+    summary = models.TextField()
+    content = models.TextField()
+    author = models.ForeignKey(User, on_delete=models.CASCADE)
+    tags = models.ManyToManyField(Tag)
+
+    class ReadSerializer:
+        # List view: minimal fields
+        fields = ["id", "title", "summary"]
+
+    class DetailSerializer:
+        # Detail view: all fields
+        fields = ["id", "title", "summary", "content", "author", "tags"]
+
+@api.viewset(model=Article)
+class ArticleViewSet(APIViewSet):
+    pass  # Schemas auto-generated from model
+```
+
+Endpoints behavior:
+- `GET /articles/` returns `[{"id": 1, "title": "...", "summary": "..."}, ...]`
+- `GET /articles/1` returns `{"id": 1, "title": "...", "summary": "...", "content": "...", "author": {...}, "tags": [...]}`
 
 ## List Filtering
 
@@ -254,6 +291,7 @@ Relations are declared via `M2MRelationSchema` objects (not tuples). Each schema
 - `get`: enable GET listing (bool)
 - `filters`: dict of `{param_name: (type, default)}` for relation-level filtering
 - `related_schema`: optional pre-built schema for the related model (auto-generated if the `model` is a `ModelSerializer`)
+- `serializer_class`: optional `Serializer` class for plain Django models. When provided, `related_schema` is auto-generated from the serializer. Cannot be used when `model` is a `ModelSerializer`.
 - `append_slash`: bool to control trailing slash for the GET relation endpoint path. Defaults to `False` (no trailing slash) for backward compatibility. When `True`, the GET path ends with a trailing slash.
 
 If `path` is empty it falls back to the related model verbose name (lowercase plural).
@@ -285,21 +323,43 @@ async def tags_query_params_handler(self, queryset, filters_dict):
 
 Warning: Model support
 
-- You can supply a standard Django `Model` (not a `ModelSerializer`) in `M2MRelationSchema.model`. When doing so you must provide `related_schema` manually:
+- You can supply a standard Django `Model` (not a `ModelSerializer`) in `M2MRelationSchema.model`. When doing so you must provide either `related_schema` manually or `serializer_class`:
 
-```python
-M2MRelationSchema(
-    model=Tag,                # plain django.db.models.Model
-    related_name="tags",
-    related_schema=TagOut,    # a Pydantic/Ninja Schema you define
-    add=True,
-    remove=True,
-    get=True,
-)
-```
+=== "With related_schema"
+    ```python
+    M2MRelationSchema(
+        model=Tag,                # plain django.db.models.Model
+        related_name="tags",
+        related_schema=TagOut,    # a Pydantic/Ninja Schema you define
+        add=True,
+        remove=True,
+        get=True,
+    )
+    ```
+
+=== "With serializer_class"
+    ```python
+    from ninja_aio.models import serializers
+
+    class TagSerializer(serializers.Serializer):
+        class Meta:
+            model = Tag
+            schema_out = serializers.SchemaModelConfig(fields=["id", "name"])
+
+    M2MRelationSchema(
+        model=Tag,                        # plain django.db.models.Model
+        related_name="tags",
+        serializer_class=TagSerializer,   # auto-generates related_schema
+        add=True,
+        remove=True,
+        get=True,
+    )
+    ```
 
 For `ModelSerializer` models, `related_schema` can be inferred automatically (via internal helpers).
 
+Note: You cannot use `serializer_class` when `model` is already a `ModelSerializer` - this will raise a `ValueError`.
+
 Example with filters:
 
 ```python

{django_ninja_aio_crud-2.7.0 → django_ninja_aio_crud-2.8.0}/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
 

{django_ninja_aio_crud-2.7.0 → django_ninja_aio_crud-2.8.0}/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

{django_ninja_aio_crud-2.7.0 → django_ninja_aio_crud-2.8.0}/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]