fastapi-errors-plus 0.6.2__tar.gz → 0.7.0__tar.gz

{fastapi_errors_plus-0.6.2 → fastapi_errors_plus-0.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fastapi-errors-plus
-Version: 0.6.2
+Version: 0.7.0
 Summary: Universal library for documenting errors in FastAPI endpoints
 Author-email: Igor Selivanov <seligoroff@gmail.com>
 License: MIT
@@ -30,12 +30,12 @@ Dynamic: license-file
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)
 [![FastAPI](https://img.shields.io/badge/FastAPI-0.104%2B-009688.svg)](https://fastapi.tiangolo.com/)
-[![Tests](https://img.shields.io/badge/tests-72%20passed-success.svg)](https://github.com/seligoroff/fastapi-errors-plus)
-[![Coverage](https://img.shields.io/badge/coverage-83%25-green.svg)](https://github.com/seligoroff/fastapi-errors-plus)
+[![Tests](https://img.shields.io/badge/tests-101-success.svg)](https://github.com/seligoroff/fastapi-errors-plus)
+[![Coverage](https://img.shields.io/badge/coverage-80%25%2B-green.svg)](https://github.com/seligoroff/fastapi-errors-plus)
 
 Universal library for documenting errors in FastAPI endpoints.
 
-> [Русская версия README](README.ru.md)
+> [Русская версия README](https://github.com/seligoroff/fastapi-errors-plus/blob/main/README.ru.md)
 
 ## Philosophy
 
@@ -207,6 +207,39 @@ def delete_item(id: int):
     pass
 ```
 
+#### OpenAPI extras (`schema`) next to examples
+
+ADR-style payloads (`code`, `detail`, optional `context`) need a **`schema`** in the spec besides **`examples`**. On **`BaseErrorDTO`** / **`StandardErrorDTO`** use **`openapi_json_extras`** (a dict merged under `content["application/json"]` — omit `example` / `examples` there; **`to_example()`** still defines examples):
+
+```python
+from fastapi import APIRouter, status
+from fastapi_errors_plus import BaseErrorDTO, Errors
+
+ADR_ERROR_BODY_SCHEMA = {
+    "type": "object",
+    "required": ["code", "detail"],
+    "properties": {
+        "code": {"type": "string"},
+        "detail": {"type": "string"},
+        "context": {"type": "object"},
+    },
+}
+
+business_conflict = BaseErrorDTO(
+    status_code=status.HTTP_409_CONFLICT,
+    message="BusinessRuleViolation",
+    openapi_json_extras={"schema": ADR_ERROR_BODY_SCHEMA},
+)
+
+router = APIRouter()
+
+@router.post("/items", responses=Errors(business_conflict, validation_error=False))
+def create_item():
+    ...
+```
+
+Custom **`ErrorDTO`** classes may instead define **`to_openapi_json_media_type_extras()`** returning a **`dict`**; if present and non-empty, it overrides **`openapi_json_extras`**. Any later **`dict`** in **`Errors`** for that status still overrides the same **`application/json`** keys (same precedence as merging two dicts).
+
 #### StandardErrorDTO
 
 Extended implementation for errors with multiple examples (useful for standard HTTP errors):
@@ -297,6 +330,37 @@ def update_item(id: int):
 
 The OpenAPI spec will contain both examples under the 404 status code.
 
+When merging the same status code: a **dict** wins for **`description`** over the bundled standard-flag wording; an **ErrorDTO**’s `message` can replace the description only while it still matches the library’s default label for that code (custom descriptions coming from dicts are not overwritten by DTOs).
+
+Under `content["application/json"]`, `example` / `examples` are merged as before; any **other** OpenAPI Media Type fields from a later **`dict`** (for example **`schema`**, **`encoding`**) are **copied in** as well—the later dict wins on conflict (**same rule as `description`**).  
+
+You can combine one **`ErrorDTO`** (examples) with a **`dict`** for the **same numeric status code** listing only **`schema`** (or other non-example keys) without repeating the boilerplate examples block:
+
+```python
+Errors(
+    conflict_error_doc,   # implements ErrorDTO, e.g. .for_openapi() for ADR-shaped examples
+    {
+        status.HTTP_409_CONFLICT: {
+            "description": "Business rule violation",
+            "content": {
+                "application/json": {
+                    "schema": {
+                        "type": "object",
+                        "properties": {
+                            "code": {"type": "string"},
+                            "detail": {"type": "string"},
+                            "context": {"type": "object"},
+                        },
+                    },
+                },
+            },
+        },
+    },
+)
+```
+
+Order matters only for overlaps: whichever **`dict`** is applied **later** in the **`Errors`** argument list overwrites **`schema`** / **`encoding`** (and **`model`** on the outer response dict, if provided) when the same keys appear again.
+
 ## ErrorDTO Protocol
 
 The `ErrorDTO` protocol defines the interface for error objects compatible with the library:
@@ -568,14 +632,15 @@ Errors(
 FastAPI automatically validates all parameters (Path, Query, Body), so 422 is relevant in 95%+ of endpoints. For endpoints without parameters, explicitly set `validation_error=False` or `validation_error_422=False`.
 
 **Returns:**
-- Mapping object (dict-like) that implements `Dict[int, Dict[str, Any]]` for FastAPI responses
-- Can be used directly in `responses` parameter without calling: `responses=Errors(...)`
+- A dict-like `Mapping[int, …]` suitable for FastAPI’s `responses` / OpenAPI
+- Pass the instance as-is — **do not** call it like a function: `responses=Errors(...)`
 
 #### Usage
 
 ```python
-# Call the instance to get responses dict
-responses = Errors(unauthorized=True)
+# Instances are Mapping keyed by HTTP status codes
+error_responses = Errors(unauthorized_401=True, forbidden_403=True)
+documented = error_responses[401]  # response block picked up by OpenAPI
 ```
 
 ### `ErrorDTO`
@@ -589,6 +654,8 @@ Protocol for error objects compatible with the library.
 **Required methods:**
 - `to_example() -> Dict[str, Any]` — Generate example for OpenAPI
 
+During `Errors(...)` initialization, non-`dict` objects in `*errors` missing `status_code`, `message`, or a callable `to_example` raise **`TypeError`** naming what was missing.
+
 ### `BaseErrorDTO`
 
 Base implementation of ErrorDTO Protocol for convenience.
@@ -598,6 +665,7 @@ Base implementation of ErrorDTO Protocol for convenience.
 BaseErrorDTO(
     status_code: int,
     message: str,
+    openapi_json_extras: Optional[Dict[str, Any]] = None,
 )
 ```
 
@@ -615,6 +683,7 @@ Extended implementation for errors with multiple examples.
 StandardErrorDTO(
     status_code: int,
     message: str,
+    openapi_json_extras: Optional[Dict[str, Any]] = None,
     examples: Optional[Dict[str, str]] = None,
 )
 ```
@@ -666,7 +735,7 @@ def delete_item(id: int):
 ```python
 from fastapi import APIRouter
 from fastapi_errors_plus import Errors
-from api.exceptions.dto import errors  # Your project's error DTOs
+from api.exceptions.dto import notification_not_found_error  # ErrorDTO-compatible instance
 
 router = APIRouter()
 
@@ -675,7 +744,7 @@ router = APIRouter()
     responses=Errors(
         unauthorized=True,
         forbidden=True,
-        errors.notification_not_found_error,  # Your ErrorDTO
+        notification_not_found_error,
     ),
 )
 async def delete_notification(notification_id: int):
@@ -714,40 +783,32 @@ This example shows how to use `fastapi-errors-plus` in a FastAPI project with Cl
 
 **Domain Layer** (`domain/errors.py`):
 ```python
-from typing import Protocol, Dict, Any
+from typing import Dict, Any
 
-class DomainError(Protocol):
-    """Domain error protocol compatible with ErrorDTO."""
+class DomainException(Exception):
+    """Domain exception usable as runtime error and shaped like ErrorDTO for OpenAPI."""
     status_code: int
     message: str
-    
-    def to_example(self) -> Dict[str, Any]:
-        """Generate example for OpenAPI."""
-        ...
 
-class ItemNotFoundError:
-    """Domain error for item not found."""
-    status_code = 404
-    message = "Item not found"
-    
+    def __init__(self) -> None:
+        super().__init__(self.message)
+
     def to_example(self) -> Dict[str, Any]:
         return {
-            "ItemNotFound": {
-                "value": {"detail": "Item not found"},
+            self.message: {
+                "value": {"detail": self.message},
             },
         }
 
-class ItemAlreadyExistsError:
-    """Domain error for item already exists."""
+
+class ItemNotFoundError(DomainException):
+    status_code = 404
+    message = "Item not found"
+
+
+class ItemAlreadyExistsError(DomainException):
     status_code = 409
     message = "Item already exists"
-    
-    def to_example(self) -> Dict[str, Any]:
-        return {
-            "ItemAlreadyExists": {
-                "value": {"detail": "Item already exists"},
-            },
-        }
 ```
 
 **Application Layer** (`application/use_cases.py`):

{fastapi_errors_plus-0.6.2 → fastapi_errors_plus-0.7.0}/README.md

@@ -4,12 +4,12 @@
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)
 [![FastAPI](https://img.shields.io/badge/FastAPI-0.104%2B-009688.svg)](https://fastapi.tiangolo.com/)
-[![Tests](https://img.shields.io/badge/tests-72%20passed-success.svg)](https://github.com/seligoroff/fastapi-errors-plus)
-[![Coverage](https://img.shields.io/badge/coverage-83%25-green.svg)](https://github.com/seligoroff/fastapi-errors-plus)
+[![Tests](https://img.shields.io/badge/tests-101-success.svg)](https://github.com/seligoroff/fastapi-errors-plus)
+[![Coverage](https://img.shields.io/badge/coverage-80%25%2B-green.svg)](https://github.com/seligoroff/fastapi-errors-plus)
 
 Universal library for documenting errors in FastAPI endpoints.
 
-> [Русская версия README](README.ru.md)
+> [Русская версия README](https://github.com/seligoroff/fastapi-errors-plus/blob/main/README.ru.md)
 
 ## Philosophy
 
@@ -181,6 +181,39 @@ def delete_item(id: int):
     pass
 ```
 
+#### OpenAPI extras (`schema`) next to examples
+
+ADR-style payloads (`code`, `detail`, optional `context`) need a **`schema`** in the spec besides **`examples`**. On **`BaseErrorDTO`** / **`StandardErrorDTO`** use **`openapi_json_extras`** (a dict merged under `content["application/json"]` — omit `example` / `examples` there; **`to_example()`** still defines examples):
+
+```python
+from fastapi import APIRouter, status
+from fastapi_errors_plus import BaseErrorDTO, Errors
+
+ADR_ERROR_BODY_SCHEMA = {
+    "type": "object",
+    "required": ["code", "detail"],
+    "properties": {
+        "code": {"type": "string"},
+        "detail": {"type": "string"},
+        "context": {"type": "object"},
+    },
+}
+
+business_conflict = BaseErrorDTO(
+    status_code=status.HTTP_409_CONFLICT,
+    message="BusinessRuleViolation",
+    openapi_json_extras={"schema": ADR_ERROR_BODY_SCHEMA},
+)
+
+router = APIRouter()
+
+@router.post("/items", responses=Errors(business_conflict, validation_error=False))
+def create_item():
+    ...
+```
+
+Custom **`ErrorDTO`** classes may instead define **`to_openapi_json_media_type_extras()`** returning a **`dict`**; if present and non-empty, it overrides **`openapi_json_extras`**. Any later **`dict`** in **`Errors`** for that status still overrides the same **`application/json`** keys (same precedence as merging two dicts).
+
 #### StandardErrorDTO
 
 Extended implementation for errors with multiple examples (useful for standard HTTP errors):
@@ -271,6 +304,37 @@ def update_item(id: int):
 
 The OpenAPI spec will contain both examples under the 404 status code.
 
+When merging the same status code: a **dict** wins for **`description`** over the bundled standard-flag wording; an **ErrorDTO**’s `message` can replace the description only while it still matches the library’s default label for that code (custom descriptions coming from dicts are not overwritten by DTOs).
+
+Under `content["application/json"]`, `example` / `examples` are merged as before; any **other** OpenAPI Media Type fields from a later **`dict`** (for example **`schema`**, **`encoding`**) are **copied in** as well—the later dict wins on conflict (**same rule as `description`**).  
+
+You can combine one **`ErrorDTO`** (examples) with a **`dict`** for the **same numeric status code** listing only **`schema`** (or other non-example keys) without repeating the boilerplate examples block:
+
+```python
+Errors(
+    conflict_error_doc,   # implements ErrorDTO, e.g. .for_openapi() for ADR-shaped examples
+    {
+        status.HTTP_409_CONFLICT: {
+            "description": "Business rule violation",
+            "content": {
+                "application/json": {
+                    "schema": {
+                        "type": "object",
+                        "properties": {
+                            "code": {"type": "string"},
+                            "detail": {"type": "string"},
+                            "context": {"type": "object"},
+                        },
+                    },
+                },
+            },
+        },
+    },
+)
+```
+
+Order matters only for overlaps: whichever **`dict`** is applied **later** in the **`Errors`** argument list overwrites **`schema`** / **`encoding`** (and **`model`** on the outer response dict, if provided) when the same keys appear again.
+
 ## ErrorDTO Protocol
 
 The `ErrorDTO` protocol defines the interface for error objects compatible with the library:
@@ -542,14 +606,15 @@ Errors(
 FastAPI automatically validates all parameters (Path, Query, Body), so 422 is relevant in 95%+ of endpoints. For endpoints without parameters, explicitly set `validation_error=False` or `validation_error_422=False`.
 
 **Returns:**
-- Mapping object (dict-like) that implements `Dict[int, Dict[str, Any]]` for FastAPI responses
-- Can be used directly in `responses` parameter without calling: `responses=Errors(...)`
+- A dict-like `Mapping[int, …]` suitable for FastAPI’s `responses` / OpenAPI
+- Pass the instance as-is — **do not** call it like a function: `responses=Errors(...)`
 
 #### Usage
 
 ```python
-# Call the instance to get responses dict
-responses = Errors(unauthorized=True)
+# Instances are Mapping keyed by HTTP status codes
+error_responses = Errors(unauthorized_401=True, forbidden_403=True)
+documented = error_responses[401]  # response block picked up by OpenAPI
 ```
 
 ### `ErrorDTO`
@@ -563,6 +628,8 @@ Protocol for error objects compatible with the library.
 **Required methods:**
 - `to_example() -> Dict[str, Any]` — Generate example for OpenAPI
 
+During `Errors(...)` initialization, non-`dict` objects in `*errors` missing `status_code`, `message`, or a callable `to_example` raise **`TypeError`** naming what was missing.
+
 ### `BaseErrorDTO`
 
 Base implementation of ErrorDTO Protocol for convenience.
@@ -572,6 +639,7 @@ Base implementation of ErrorDTO Protocol for convenience.
 BaseErrorDTO(
     status_code: int,
     message: str,
+    openapi_json_extras: Optional[Dict[str, Any]] = None,
 )
 ```
 
@@ -589,6 +657,7 @@ Extended implementation for errors with multiple examples.
 StandardErrorDTO(
     status_code: int,
     message: str,
+    openapi_json_extras: Optional[Dict[str, Any]] = None,
     examples: Optional[Dict[str, str]] = None,
 )
 ```
@@ -640,7 +709,7 @@ def delete_item(id: int):
 ```python
 from fastapi import APIRouter
 from fastapi_errors_plus import Errors
-from api.exceptions.dto import errors  # Your project's error DTOs
+from api.exceptions.dto import notification_not_found_error  # ErrorDTO-compatible instance
 
 router = APIRouter()
 
@@ -649,7 +718,7 @@ router = APIRouter()
     responses=Errors(
         unauthorized=True,
         forbidden=True,
-        errors.notification_not_found_error,  # Your ErrorDTO
+        notification_not_found_error,
     ),
 )
 async def delete_notification(notification_id: int):
@@ -688,40 +757,32 @@ This example shows how to use `fastapi-errors-plus` in a FastAPI project with Cl
 
 **Domain Layer** (`domain/errors.py`):
 ```python
-from typing import Protocol, Dict, Any
+from typing import Dict, Any
 
-class DomainError(Protocol):
-    """Domain error protocol compatible with ErrorDTO."""
+class DomainException(Exception):
+    """Domain exception usable as runtime error and shaped like ErrorDTO for OpenAPI."""
     status_code: int
     message: str
-    
-    def to_example(self) -> Dict[str, Any]:
-        """Generate example for OpenAPI."""
-        ...
 
-class ItemNotFoundError:
-    """Domain error for item not found."""
-    status_code = 404
-    message = "Item not found"
-    
+    def __init__(self) -> None:
+        super().__init__(self.message)
+
     def to_example(self) -> Dict[str, Any]:
         return {
-            "ItemNotFound": {
-                "value": {"detail": "Item not found"},
+            self.message: {
+                "value": {"detail": self.message},
             },
         }
 
-class ItemAlreadyExistsError:
-    """Domain error for item already exists."""
+
+class ItemNotFoundError(DomainException):
+    status_code = 404
+    message = "Item not found"
+
+
+class ItemAlreadyExistsError(DomainException):
     status_code = 409
     message = "Item already exists"
-    
-    def to_example(self) -> Dict[str, Any]:
-        return {
-            "ItemAlreadyExists": {
-                "value": {"detail": "Item already exists"},
-            },
-        }
 ```
 
 **Application Layer** (`application/use_cases.py`):

{fastapi_errors_plus-0.6.2 → fastapi_errors_plus-0.7.0}/fastapi_errors_plus/__init__.py

@@ -10,5 +10,5 @@ __all__ = [
     "BaseErrorDTO",  # Base implementation (optional)
     "StandardErrorDTO",  # Extended implementation (optional)
 ]
-__version__ = "0.6.2"
+__version__ = "0.7.0"
 

{fastapi_errors_plus-0.6.2 → fastapi_errors_plus-0.7.0}/fastapi_errors_plus/base.py

@@ -37,6 +37,12 @@ class BaseErrorDTO:
     message: str
     """Error message description."""
     
+    openapi_json_extras: Optional[Dict[str, Any]] = field(default=None)
+    """Optional OpenAPI fragment under ``content['application/json']`` besides examples,
+    typically ``{\"schema\": ...}`` or ``encoding``. Do **not** put ``example`` / ``examples``
+    here — use :meth:`to_example`. Arbitrary implementations may instead implement
+    :meth:`to_openapi_json_media_type_extras`; that return value wins over this attribute."""
+    
     def to_example(self) -> Dict[str, Any]:
         """Generate example for OpenAPI.
         

{fastapi_errors_plus-0.6.2 → fastapi_errors_plus-0.7.0}/fastapi_errors_plus/errors.py

@@ -7,6 +7,43 @@ from fastapi import status
 
 from fastapi_errors_plus.protocol import ErrorDTO
 
+# Starlette (via FastAPI) prefers HTTP_422_UNPROCESSABLE_CONTENT over ENTITY.
+# Older pins may lack CONTENT (import crash); avoid nested getattr(, default=)
+# touching ENTITY when CONTENT exists (DeprecationWarning).
+_HTTP_422 = getattr(status, "HTTP_422_UNPROCESSABLE_CONTENT", None)
+if _HTTP_422 is None:
+    _HTTP_422 = getattr(status, "HTTP_422_UNPROCESSABLE_ENTITY", 422)
+
+# OpenAPI Media Type: merge example/examples separately; other keys (schema, encoding, …) from an extra dict win.
+_OPENAPI_MEDIA_TYPE_EXAMPLE_KEYS = frozenset({"example", "examples"})
+
+
+def _merge_openapi_application_json_non_example(
+    existing_json: Dict[str, Any],
+    response_json: Dict[str, Any],
+) -> None:
+    """Apply schema/encoding/extra fields from incoming media type; incoming overwrites on conflict."""
+    for key, value in response_json.items():
+        if key not in _OPENAPI_MEDIA_TYPE_EXAMPLE_KEYS:
+            existing_json[key] = value
+
+
+def _pick_error_dto_application_json_extra(error_dto: Any) -> Optional[Dict[str, Any]]:
+    """Optional OpenAPI ``application/json`` keys from DTO (e.g. ``schema``, ``encoding``).
+
+    Prefer ``to_openapi_json_media_type_extras()`` when present and returns a truthy mapping;
+    otherwise ``openapi_json_extras`` attribute. Must not rely on ``example`` / ``examples`` here —
+    ``to_example()`` covers those."""
+    getter = getattr(error_dto, "to_openapi_json_media_type_extras", None)
+    if callable(getter):
+        out = getter()
+        if isinstance(out, dict) and out:
+            return dict(out)
+    extra = getattr(error_dto, "openapi_json_extras", None)
+    if isinstance(extra, dict) and extra:
+        return dict(extra)
+    return None
+
 
 class Errors(Mapping):
     """Universal class for documenting errors in FastAPI endpoints.
@@ -140,7 +177,7 @@ class Errors(Mapping):
         
         if add_422:
             self._add_standard_error(
-                status.HTTP_422_UNPROCESSABLE_CONTENT,
+                _HTTP_422,
                 "Validation Error",
                 {"detail": "Validation error"},
             )
@@ -239,7 +276,7 @@ class Errors(Mapping):
     STANDARD_DESCRIPTIONS = {
         status.HTTP_401_UNAUTHORIZED: "Unauthorized",
         status.HTTP_403_FORBIDDEN: "Forbidden",
-        status.HTTP_422_UNPROCESSABLE_CONTENT: "Validation Error",
+        _HTTP_422: "Validation Error",
         status.HTTP_500_INTERNAL_SERVER_ERROR: "Internal Server Error",
     }
     
@@ -263,7 +300,7 @@ class Errors(Mapping):
         standard_keys = {
             status.HTTP_401_UNAUTHORIZED: "StandardUnauthorized",
             status.HTTP_403_FORBIDDEN: "StandardForbidden",
-            status.HTTP_422_UNPROCESSABLE_CONTENT: "StandardValidationError",
+            _HTTP_422: "StandardValidationError",
             status.HTTP_500_INTERNAL_SERVER_ERROR: "StandardInternalServerError",
         }
         example_key = standard_keys.get(status_code, f"Standard{status_code}")
@@ -322,6 +359,10 @@ class Errors(Mapping):
                 if "description" in response_data:
                     existing["description"] = response_data["description"]
                 
+                # FastAPI-style shorthand on the response object (incoming dict wins)
+                if "model" in response_data:
+                    existing["model"] = response_data["model"]
+                
                 # Merge content
                 if "content" in response_data:
                     existing_content = existing.setdefault("content", {})
@@ -332,6 +373,8 @@ class Errors(Mapping):
                         existing_json = existing_content.setdefault("application/json", {})
                         response_json = response_content["application/json"]
                         
+                        _merge_openapi_application_json_non_example(existing_json, response_json)
+                        
                         # Handle example/examples
                         if "examples" in response_json:
                             # Response has examples
@@ -400,14 +443,16 @@ class Errors(Mapping):
         """
         status_code = error_dto.status_code
         examples = error_dto.to_example()
-        
+        dto_extras = _pick_error_dto_application_json_extra(error_dto)
+
         if status_code not in self._responses:
+            application_json: Dict[str, Any] = {"examples": examples}
+            if dto_extras is not None:
+                _merge_openapi_application_json_non_example(application_json, dto_extras)
             self._responses[status_code] = {
                 "description": error_dto.message,
                 "content": {
-                    "application/json": {
-                        "examples": examples,
-                    },
+                    "application/json": application_json,
                 },
             }
         else:
@@ -446,7 +491,10 @@ class Errors(Mapping):
             # Merge new examples from ErrorDTO
             existing_examples.update(examples)
             content_json["examples"] = existing_examples
-    
+            
+            if dto_extras is not None:
+                _merge_openapi_application_json_non_example(content_json, dto_extras)
+
     # Mapping protocol implementation
     def __getitem__(self, key: int) -> Dict[str, Any]:
         """Get response for status code.

{fastapi_errors_plus-0.6.2 → fastapi_errors_plus-0.7.0}/fastapi_errors_plus/protocol.py

@@ -8,6 +8,13 @@ class ErrorDTO(Protocol):
     
     Any class implementing this protocol can be used with Errors().
     
+    Optionally, objects may expose **OpenAPI extras** besides examples:
+    
+    - ``openapi_json_extras``: ``dict`` merged into ``content["application/json"]``  
+      (e.g. ``{"schema": ...}`` — do **not** use for ``example`` / ``examples``).
+    - or ``to_openapi_json_media_type_extras() -> Optional[dict]``: if present and returns a
+      non-empty ``dict``, it **takes precedence** over ``openapi_json_extras``.
+    
     Example:
         ```python
         class MyError:

{fastapi_errors_plus-0.6.2 → fastapi_errors_plus-0.7.0}/fastapi_errors_plus.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fastapi-errors-plus
-Version: 0.6.2
+Version: 0.7.0
 Summary: Universal library for documenting errors in FastAPI endpoints
 Author-email: Igor Selivanov <seligoroff@gmail.com>
 License: MIT
@@ -30,12 +30,12 @@ Dynamic: license-file
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)
 [![FastAPI](https://img.shields.io/badge/FastAPI-0.104%2B-009688.svg)](https://fastapi.tiangolo.com/)
-[![Tests](https://img.shields.io/badge/tests-72%20passed-success.svg)](https://github.com/seligoroff/fastapi-errors-plus)
-[![Coverage](https://img.shields.io/badge/coverage-83%25-green.svg)](https://github.com/seligoroff/fastapi-errors-plus)
+[![Tests](https://img.shields.io/badge/tests-101-success.svg)](https://github.com/seligoroff/fastapi-errors-plus)
+[![Coverage](https://img.shields.io/badge/coverage-80%25%2B-green.svg)](https://github.com/seligoroff/fastapi-errors-plus)
 
 Universal library for documenting errors in FastAPI endpoints.
 
-> [Русская версия README](README.ru.md)
+> [Русская версия README](https://github.com/seligoroff/fastapi-errors-plus/blob/main/README.ru.md)
 
 ## Philosophy
 
@@ -207,6 +207,39 @@ def delete_item(id: int):
     pass
 ```
 
+#### OpenAPI extras (`schema`) next to examples
+
+ADR-style payloads (`code`, `detail`, optional `context`) need a **`schema`** in the spec besides **`examples`**. On **`BaseErrorDTO`** / **`StandardErrorDTO`** use **`openapi_json_extras`** (a dict merged under `content["application/json"]` — omit `example` / `examples` there; **`to_example()`** still defines examples):
+
+```python
+from fastapi import APIRouter, status
+from fastapi_errors_plus import BaseErrorDTO, Errors
+
+ADR_ERROR_BODY_SCHEMA = {
+    "type": "object",
+    "required": ["code", "detail"],
+    "properties": {
+        "code": {"type": "string"},
+        "detail": {"type": "string"},
+        "context": {"type": "object"},
+    },
+}
+
+business_conflict = BaseErrorDTO(
+    status_code=status.HTTP_409_CONFLICT,
+    message="BusinessRuleViolation",
+    openapi_json_extras={"schema": ADR_ERROR_BODY_SCHEMA},
+)
+
+router = APIRouter()
+
+@router.post("/items", responses=Errors(business_conflict, validation_error=False))
+def create_item():
+    ...
+```
+
+Custom **`ErrorDTO`** classes may instead define **`to_openapi_json_media_type_extras()`** returning a **`dict`**; if present and non-empty, it overrides **`openapi_json_extras`**. Any later **`dict`** in **`Errors`** for that status still overrides the same **`application/json`** keys (same precedence as merging two dicts).
+
 #### StandardErrorDTO
 
 Extended implementation for errors with multiple examples (useful for standard HTTP errors):
@@ -297,6 +330,37 @@ def update_item(id: int):
 
 The OpenAPI spec will contain both examples under the 404 status code.
 
+When merging the same status code: a **dict** wins for **`description`** over the bundled standard-flag wording; an **ErrorDTO**’s `message` can replace the description only while it still matches the library’s default label for that code (custom descriptions coming from dicts are not overwritten by DTOs).
+
+Under `content["application/json"]`, `example` / `examples` are merged as before; any **other** OpenAPI Media Type fields from a later **`dict`** (for example **`schema`**, **`encoding`**) are **copied in** as well—the later dict wins on conflict (**same rule as `description`**).  
+
+You can combine one **`ErrorDTO`** (examples) with a **`dict`** for the **same numeric status code** listing only **`schema`** (or other non-example keys) without repeating the boilerplate examples block:
+
+```python
+Errors(
+    conflict_error_doc,   # implements ErrorDTO, e.g. .for_openapi() for ADR-shaped examples
+    {
+        status.HTTP_409_CONFLICT: {
+            "description": "Business rule violation",
+            "content": {
+                "application/json": {
+                    "schema": {
+                        "type": "object",
+                        "properties": {
+                            "code": {"type": "string"},
+                            "detail": {"type": "string"},
+                            "context": {"type": "object"},
+                        },
+                    },
+                },
+            },
+        },
+    },
+)
+```
+
+Order matters only for overlaps: whichever **`dict`** is applied **later** in the **`Errors`** argument list overwrites **`schema`** / **`encoding`** (and **`model`** on the outer response dict, if provided) when the same keys appear again.
+
 ## ErrorDTO Protocol
 
 The `ErrorDTO` protocol defines the interface for error objects compatible with the library:
@@ -568,14 +632,15 @@ Errors(
 FastAPI automatically validates all parameters (Path, Query, Body), so 422 is relevant in 95%+ of endpoints. For endpoints without parameters, explicitly set `validation_error=False` or `validation_error_422=False`.
 
 **Returns:**
-- Mapping object (dict-like) that implements `Dict[int, Dict[str, Any]]` for FastAPI responses
-- Can be used directly in `responses` parameter without calling: `responses=Errors(...)`
+- A dict-like `Mapping[int, …]` suitable for FastAPI’s `responses` / OpenAPI
+- Pass the instance as-is — **do not** call it like a function: `responses=Errors(...)`
 
 #### Usage
 
 ```python
-# Call the instance to get responses dict
-responses = Errors(unauthorized=True)
+# Instances are Mapping keyed by HTTP status codes
+error_responses = Errors(unauthorized_401=True, forbidden_403=True)
+documented = error_responses[401]  # response block picked up by OpenAPI
 ```
 
 ### `ErrorDTO`
@@ -589,6 +654,8 @@ Protocol for error objects compatible with the library.
 **Required methods:**
 - `to_example() -> Dict[str, Any]` — Generate example for OpenAPI
 
+During `Errors(...)` initialization, non-`dict` objects in `*errors` missing `status_code`, `message`, or a callable `to_example` raise **`TypeError`** naming what was missing.
+
 ### `BaseErrorDTO`
 
 Base implementation of ErrorDTO Protocol for convenience.
@@ -598,6 +665,7 @@ Base implementation of ErrorDTO Protocol for convenience.
 BaseErrorDTO(
     status_code: int,
     message: str,
+    openapi_json_extras: Optional[Dict[str, Any]] = None,
 )
 ```
 
@@ -615,6 +683,7 @@ Extended implementation for errors with multiple examples.
 StandardErrorDTO(
     status_code: int,
     message: str,
+    openapi_json_extras: Optional[Dict[str, Any]] = None,
     examples: Optional[Dict[str, str]] = None,
 )
 ```
@@ -666,7 +735,7 @@ def delete_item(id: int):
 ```python
 from fastapi import APIRouter
 from fastapi_errors_plus import Errors
-from api.exceptions.dto import errors  # Your project's error DTOs
+from api.exceptions.dto import notification_not_found_error  # ErrorDTO-compatible instance
 
 router = APIRouter()
 
@@ -675,7 +744,7 @@ router = APIRouter()
     responses=Errors(
         unauthorized=True,
         forbidden=True,
-        errors.notification_not_found_error,  # Your ErrorDTO
+        notification_not_found_error,
     ),
 )
 async def delete_notification(notification_id: int):
@@ -714,40 +783,32 @@ This example shows how to use `fastapi-errors-plus` in a FastAPI project with Cl
 
 **Domain Layer** (`domain/errors.py`):
 ```python
-from typing import Protocol, Dict, Any
+from typing import Dict, Any
 
-class DomainError(Protocol):
-    """Domain error protocol compatible with ErrorDTO."""
+class DomainException(Exception):
+    """Domain exception usable as runtime error and shaped like ErrorDTO for OpenAPI."""
     status_code: int
     message: str
-    
-    def to_example(self) -> Dict[str, Any]:
-        """Generate example for OpenAPI."""
-        ...
 
-class ItemNotFoundError:
-    """Domain error for item not found."""
-    status_code = 404
-    message = "Item not found"
-    
+    def __init__(self) -> None:
+        super().__init__(self.message)
+
     def to_example(self) -> Dict[str, Any]:
         return {
-            "ItemNotFound": {
-                "value": {"detail": "Item not found"},
+            self.message: {
+                "value": {"detail": self.message},
             },
         }
 
-class ItemAlreadyExistsError:
-    """Domain error for item already exists."""
+
+class ItemNotFoundError(DomainException):
+    status_code = 404
+    message = "Item not found"
+
+
+class ItemAlreadyExistsError(DomainException):
     status_code = 409
     message = "Item already exists"
-    
-    def to_example(self) -> Dict[str, Any]:
-        return {
-            "ItemAlreadyExists": {
-                "value": {"detail": "Item already exists"},
-            },
-        }
 ```
 
 **Application Layer** (`application/use_cases.py`):

{fastapi_errors_plus-0.6.2 → fastapi_errors_plus-0.7.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "fastapi-errors-plus"
-version = "0.6.2"
+version = "0.7.0"
 description = "Universal library for documenting errors in FastAPI endpoints"
 readme = "README.md"
 requires-python = ">=3.8"

{fastapi_errors_plus-0.6.2 → fastapi_errors_plus-0.7.0}/tests/test_base.py

@@ -69,6 +69,40 @@ class TestBaseErrorDTO:
         assert "Item not found" in examples
         assert examples["Item not found"]["value"] == {"detail": "Item not found"}
 
+    def test_base_error_dto_openapi_json_extras_schema(self):
+        """Schema beside examples via openapi_json_extras."""
+        adr_schema = {
+            "type": "object",
+            "required": ["code", "detail"],
+            "properties": {
+                "code": {"type": "string"},
+                "detail": {"type": "string"},
+                "context": {"type": "object"},
+            },
+        }
+        error = BaseErrorDTO(
+            status_code=409,
+            message="Conflict",
+            openapi_json_extras={"schema": adr_schema},
+        )
+        merged = Errors(error, validation_error=False)
+        aj = merged[409]["content"]["application/json"]
+        assert aj["schema"] == adr_schema
+        assert "Conflict" in aj["examples"]
+
+    def test_standard_error_dto_openapi_json_extras(self):
+        adr_schema = {"$ref": "#/components/schemas/AppError"}
+        error = StandardErrorDTO(
+            status_code=422,
+            message="Bad",
+            examples={"One": "msg"},
+            openapi_json_extras={"schema": adr_schema},
+        )
+        merged = Errors(error, validation_error=False)
+        aj = merged[422]["content"]["application/json"]
+        assert aj["schema"] == adr_schema
+        assert "One" in aj["examples"]
+
 
 @pytest.mark.unit
 class TestStandardErrorDTO:

{fastapi_errors_plus-0.6.2 → fastapi_errors_plus-0.7.0}/tests/test_errors.py

@@ -300,6 +300,159 @@ class TestErrorsMergeExamples:
         assert "examples" in content or "example" in content
 
 
+@pytest.mark.unit
+class TestErrorsOpenApiSchemaMerge:
+    """Merging schema / non-example Media Type keys with ErrorDTO or other dict fragments."""
+
+    def test_merge_error_dto_then_dict_adds_schema(self, simple_error_dto):
+        """Examples from ErrorDTO plus OpenAPI schema from a second fragment (same status)."""
+        error_dto = simple_error_dto(
+            status_code=status.HTTP_404_NOT_FOUND,
+            message="NotFound",
+            detail="nothing",
+        )
+        schema_frag = {"$ref": "#/components/schemas/AppError"}
+        errors = Errors(
+            error_dto,
+            {
+                status.HTTP_404_NOT_FOUND: {
+                    "content": {
+                        "application/json": {
+                            "schema": schema_frag,
+                        },
+                    },
+                },
+            },
+            validation_error=False,
+        )
+        aj = errors[status.HTTP_404_NOT_FOUND]["content"]["application/json"]
+        assert aj["schema"] == schema_frag
+        assert len(aj["examples"]) >= 1
+        assert "NotFound" in aj["examples"]
+
+    def test_merge_dict_schema_then_error_dto_keeps_schema(self, simple_error_dto):
+        """Schema-only fragment first; DTO merges examples without dropping schema."""
+        schema_frag = {
+            "type": "object",
+            "properties": {
+                "code": {"type": "string"},
+                "detail": {"type": "string"},
+            },
+        }
+        error_dto = simple_error_dto(
+            status_code=status.HTTP_404_NOT_FOUND,
+            message="NotFound",
+            detail="nothing",
+        )
+        errors = Errors(
+            {
+                status.HTTP_404_NOT_FOUND: {
+                    "content": {"application/json": {"schema": schema_frag}},
+                },
+            },
+            error_dto,
+            validation_error=False,
+        )
+        aj = errors[status.HTTP_404_NOT_FOUND]["content"]["application/json"]
+        assert aj["schema"] == schema_frag
+        assert "NotFound" in aj["examples"]
+
+    def test_later_dict_schema_overwrites_earlier(self):
+        """Second dict for the same status overwrites schema (dict wins, same as description)."""
+        errors = Errors(
+            {
+                status.HTTP_404_NOT_FOUND: {
+                    "content": {"application/json": {"schema": {"type": "string"}}},
+                },
+            },
+            {
+                status.HTTP_404_NOT_FOUND: {
+                    "content": {"application/json": {"schema": {"type": "object"}}},
+                },
+            },
+            validation_error=False,
+        )
+        assert (
+            errors[status.HTTP_404_NOT_FOUND]["content"]["application/json"]["schema"]["type"]
+            == "object"
+        )
+
+    def test_merge_non_example_encoding_key_from_dict(self):
+        errors = Errors(
+            {
+                status.HTTP_404_NOT_FOUND: {
+                    "content": {"application/json": {"encoding": "utf-8"}},
+                },
+            },
+            validation_error=False,
+        )
+        assert (
+            errors[status.HTTP_404_NOT_FOUND]["content"]["application/json"]["encoding"]
+            == "utf-8"
+        )
+
+    def test_openapi_json_extras_without_second_fragment_dict(self):
+        """ADR-style payload: schema on BaseErrorDTO, no duplicate status dict required."""
+        from fastapi_errors_plus import BaseErrorDTO
+
+        adr_schema = {
+            "type": "object",
+            "properties": {
+                "code": {"type": "string"},
+                "detail": {"type": "string"},
+                "context": {"type": "object"},
+            },
+        }
+        err = BaseErrorDTO(
+            status_code=status.HTTP_409_CONFLICT,
+            message="BusinessRule",
+            openapi_json_extras={
+                "schema": adr_schema,
+            },
+        )
+        errors = Errors(err, validation_error=False)
+        aj = errors[status.HTTP_409_CONFLICT]["content"]["application/json"]
+        assert aj["schema"] is adr_schema
+        assert aj["examples"]["BusinessRule"]["value"]["detail"] == "BusinessRule"
+
+    def test_later_dict_overwrites_schema_from_dto_openapi_json_extras(self):
+        from fastapi_errors_plus import BaseErrorDTO
+
+        dto = BaseErrorDTO(
+            status_code=status.HTTP_404_NOT_FOUND,
+            message="Missing",
+            openapi_json_extras={"schema": {"type": "string"}},
+        )
+        errors = Errors(
+            dto,
+            {
+                status.HTTP_404_NOT_FOUND: {
+                    "content": {"application/json": {"schema": {"type": "object"}}},
+                },
+            },
+            validation_error=False,
+        )
+        schema = errors[status.HTTP_404_NOT_FOUND]["content"]["application/json"]["schema"]
+        assert schema["type"] == "object"
+
+    def test_to_openapi_json_media_type_extras_overrides_attribute(self):
+        class CustomDTO:
+            status_code = status.HTTP_403_FORBIDDEN
+            message = "Denied"
+            openapi_json_extras = {"schema": {"type": "string"}}
+
+            def to_example(self):  # type: ignore[no-untyped-def]
+                return {
+                    self.message: {"value": {"detail": "no"}},
+                }
+
+            def to_openapi_json_media_type_extras(self):  # type: ignore[no-untyped-def]
+                return {"schema": {"description": "from method"}}
+
+        errors = Errors(CustomDTO(), validation_error=False)
+        assert errors[403]["content"]["application/json"]["schema"]["description"] == "from method"
+
+
 @pytest.mark.unit
 class TestErrorsMixed:
     """Tests for mixed usage (flags + dict + ErrorDTO)."""