Fixed docs, added example support

mr-fatalyst · mr-fatalyst · commit f27fd9b1b2a9 · 2026-02-08T16:24:56.000+01:00
diff --git a/docs/advanced/architecture.md b/docs/advanced/architecture.md
@@ -253,21 +253,21 @@ class RequestData:
     """Unified request data container"""
     def __init__(
         self,
-        path_params: dict[str, Any],
-        query_params: dict[str, Any],
-        headers: dict[str, str],
-        cookies: dict[str, str],
-        body: dict[str, Any] | None = None,
-        form_data: dict[str, Any] | None = None,
-        files: dict[str, Any] | None = None,
+        path_params: dict[str, Any] = None,
+        query_params: dict[str, Any] = None,
+        headers: dict[str, str] = None,
+        cookies: dict[str, str] = None,
+        body: Any = None,
+        form_data: dict[str, Any] = None,
+        files: dict[str, FileUpload | list[FileUpload]] = None,
     ):
-        self.path_params = path_params
-        self.query_params = query_params
-        self.headers = headers
-        self.cookies = cookies
+        self.path_params = path_params or {}
+        self.query_params = query_params or {}
+        self.headers = headers or {}
+        self.cookies = cookies or {}
         self.body = body
-        self.form_data = form_data
-        self.files = files
+        self.form_data = form_data or {}
+        self.files = files or {}
 ```
 
 **Extractor Interface:**
diff --git a/docs/advanced/architecture_quick_reference.md b/docs/advanced/architecture_quick_reference.md
@@ -83,7 +83,7 @@ sequenceDiagram
 | `BaseRouter` | `fastopenapi/core/router.py` | Route registration, OpenAPI generation |
 | `BaseAdapter` | `fastopenapi/routers/base.py` | Request pipeline orchestration |
 | `FrameworkRouter` | `fastopenapi/routers/{framework}/` | Framework integration (3 methods) |
-| `RequestDataExtractor` | `fastopenapi/routers/extractors.py` | Extract data from requests |
+| `BaseRequestDataExtractor` / `BaseAsyncRequestDataExtractor` | `fastopenapi/routers/extractors.py` | Extract data from requests (sync / async) |
 | `ParameterResolver` | `fastopenapi/resolution/resolver.py` | Parameter validation |
 | `DependencyResolver` | `fastopenapi/core/dependency_resolver.py` | Dependency injection |
 | `ResponseBuilder` | `fastopenapi/response/builder.py` | Response serialization |
diff --git a/docs/advanced/custom_routers.md b/docs/advanced/custom_routers.md
@@ -427,9 +427,10 @@ class RouteInfo:
 Wrapper for framework request (from `fastopenapi.routers.common`):
 
 ```python
+@dataclass(slots=True, frozen=True)
 class RequestEnvelope:
-    request: Any      # Framework's request object
-    path_params: dict # Path parameters extracted by framework
+    path_params: dict[str, str]  # Path parameters extracted by framework
+    request: Any | None          # Framework's request object
 ```
 
 ### Response
diff --git a/docs/advanced/openapi_customization.md b/docs/advanced/openapi_customization.md
@@ -34,11 +34,11 @@ The router constructor supports the following parameters:
 | `docs_url` | str \| None | "/docs" | Swagger UI URL |
 | `redoc_url` | str \| None | "/redoc" | ReDoc URL |
 | `openapi_url` | str \| None | "/openapi.json" | OpenAPI schema URL |
-
-> **Note:** Setting any URL to `None` disables all documentation endpoints at once.
 | `openapi_version` | str | "3.0.0" | OpenAPI specification version |
 | `security_scheme` | SecuritySchemeType \| None | BEARER_JWT | Default security scheme |
 
+> **Note:** Setting any URL to `None` disables all documentation endpoints at once.
+
 ## Tags
 
 Organize endpoints with tags:
@@ -242,7 +242,7 @@ def list_users(
 ### API Key in Header
 
 ```python
-from fastopenapi.core.constants import SecuritySchemeType
+from fastopenapi import SecuritySchemeType
 
 router = FlaskRouter(
     app=app,
diff --git a/docs/api_reference/routers.md b/docs/api_reference/routers.md
@@ -469,7 +469,7 @@ if __name__ == "__main__":
 Set the security scheme for OpenAPI documentation:
 
 ```python
-from fastopenapi.core.constants import SecuritySchemeType
+from fastopenapi import SecuritySchemeType
 
 # Bearer JWT (default)
 router = FlaskRouter(
diff --git a/docs/community/contributing.md b/docs/community/contributing.md
@@ -84,8 +84,7 @@ pre-commit run --all-files
 ## Documentation
 
 If your change affects public APIs or behavior, update the relevant documentation:
-- `docs/en/`
-- If possible, update other languages too (optional)
+- `docs/`
 
 ---
 
diff --git a/docs/examples/authentication.md b/docs/examples/authentication.md
@@ -12,7 +12,7 @@ from pydantic import BaseModel
 from datetime import datetime, timedelta
 import secrets
 import hashlib
-from fastopenapi import Header, Body, Depends, Security
+from fastopenapi import Header, Depends, Security
 from fastopenapi.routers import FlaskRouter
 from fastopenapi.errors import AuthenticationError, ResourceConflictError
 
diff --git a/docs/frameworks/django.md b/docs/frameworks/django.md
@@ -797,7 +797,7 @@ FastOpenAPI automatically converts common Django exceptions:
 # These are automatically handled:
 # - Http404 -> 404 error
 # - PermissionDenied -> 403 error
-# - SuspiciousOperation -> 400 error
+# - BadRequest -> 400 error
 ```
 
 ## Next Steps
diff --git a/docs/frameworks/flask.md b/docs/frameworks/flask.md
@@ -48,7 +48,7 @@ Flask uses `<type:name>` syntax, but FastOpenAPI converts `{name}` automatically
 def get_user(user_id: int):
     return {"user_id": user_id}
 
-# Both generate the same Flask route: /users/<int:user_id>
+# Both generate the same Flask route: /users/<user_id>
 ```
 
 ## Request Data
diff --git a/docs/frameworks/overview.md b/docs/frameworks/overview.md
@@ -4,16 +4,16 @@ FastOpenAPI supports 8 popular Python web frameworks. This guide helps you choos
 
 ## Supported Frameworks
 
-| Framework | Type | Async | Python 3.10+ | Best For |
-|-----------|------|-------|--------------|----------|
-| **Flask** | WSGI | No | Yes | Traditional web apps, simple APIs |
-| **Django** | WSGI/ASGI | Both | Yes | Full-featured web applications |
-| **Starlette** | ASGI | Yes | Yes | Modern async APIs, high performance |
-| **Quart** | ASGI | Yes | Yes | Async Flask alternative |
-| **AIOHTTP** | ASGI | Yes | Yes | Async HTTP client/server |
-| **Sanic** | ASGI | Yes | Yes | Speed-focused async framework |
-| **Falcon** | WSGI/ASGI | Both | Yes | Minimalist APIs, microservices |
-| **Tornado** | Async | Yes | Yes | Long-lived connections, WebSockets |
+| Framework | Async | Python 3.10+ | Best For |
+|-----------|-------|--------------|----------|
+| **Flask** | No | Yes | Traditional web apps, simple APIs |
+| **Django** | Both | Yes | Full-featured web applications |
+| **Starlette** | Yes | Yes | Modern async APIs, high performance |
+| **Quart** | Yes | Yes | Async Flask alternative |
+| **AIOHTTP** | Yes | Yes | Async HTTP client/server |
+| **Sanic** | Yes | Yes | Speed-focused async framework |
+| **Falcon** | Both | Yes | Minimalist APIs, microservices |
+| **Tornado** | Yes | Yes | Long-lived connections, WebSockets |
 
 ## Quick Comparison
 
@@ -329,7 +329,7 @@ def get_user(user_id: int):
 | **Form Handling** | Extension | Yes | Yes | Yes | No | Yes | No | Yes |
 | **Session Management** | Extension | Yes | Middleware | Extension | No | Extension | No | Yes |
 | **Template Engine** | Jinja2 | Django Templates | Jinja2 | Jinja2 | Jinja2 | Jinja2 | No | Native |
-| **Deployment** | WSGI | WSGI/ASGI | ASGI | ASGI | ASGI | ASGI | WSGI/ASGI | ASGI |
+| **Deployment** | Sync | Sync/Async | Async | Async | Async | Async | Sync/Async | Async |
 
 *Django and Falcon support both sync and async
 
diff --git a/docs/guide/dependencies.md b/docs/guide/dependencies.md
@@ -17,7 +17,7 @@ Dependencies are reusable functions that can be injected into your endpoints. Th
 ### Simple Dependency
 
 ```python
-from fastopenapi import Depends
+from fastopenapi import Depends, Query
 
 def get_query_param(q: str = Query(None)):
     return q or "default"
@@ -30,6 +30,9 @@ def search(query: str = Depends(get_query_param)):
 ### Dependency with Logic
 
 ```python
+from fastopenapi import Header
+from fastopenapi.errors import AuthenticationError
+
 def get_current_user(token: str = Header(..., alias="Authorization")):
     if not token.startswith("Bearer "):
         raise AuthenticationError("Invalid token format")
diff --git a/docs/guide/security.md b/docs/guide/security.md
@@ -12,7 +12,7 @@ Set the security scheme when creating the router:
 
 ```python
 from fastopenapi.routers import FlaskRouter
-from fastopenapi.core.constants import SecuritySchemeType
+from fastopenapi import SecuritySchemeType
 
 router = FlaskRouter(
     app=app,
diff --git a/docs/guide/validation.md b/docs/guide/validation.md
@@ -62,7 +62,6 @@ class Product(BaseModel):
 - `min_length` - Minimum string length
 - `max_length` - Maximum string length
 - `pattern` - Regex pattern (string must match)
-- `strip_whitespace` - Remove leading/trailing whitespace
 
 ### Numeric Constraints
 
diff --git a/docs/index.md b/docs/index.md
@@ -111,7 +111,7 @@ def list_items(db = Depends(get_db)):
 
 **Security Schemes**
 ```python
-from fastopenapi import Security
+from fastopenapi import Security, SecuritySchemeType
 
 router = FlaskRouter(
     app=app,
diff --git a/fastopenapi/__init__.py b/fastopenapi/__init__.py
@@ -1,4 +1,5 @@
 from fastopenapi.__version__ import __version__
+from fastopenapi.core.constants import SecuritySchemeType
 from fastopenapi.core.params import (
     Body,
     Cookie,
@@ -18,6 +19,7 @@
     # types
     "FileUpload",
     "Response",
+    "SecuritySchemeType",
     # params
     "Query",
     "Path",
diff --git a/fastopenapi/core/params.py b/fastopenapi/core/params.py
@@ -33,13 +33,15 @@ def __init__(
         allow_inf_nan: bool | None = None,
         max_digits: int | None = None,
         decimal_places: int | None = None,
+        example: Any | None = None,
         examples: list[Any] | None = None,
         deprecated: bool | None = None,
         include_in_schema: bool = True,
         json_schema_extra: dict[str, Any] | None = None,
         **extra: Any,
     ):
         # OpenAPI specific attributes
+        self.example = example
         self.examples = examples
         self.include_in_schema = include_in_schema
 
@@ -73,6 +75,7 @@ def __init__(
 
         super().__init__(**filtered_kwargs)
 
+        self.example = example
         self.examples = examples
         self.include_in_schema = include_in_schema
 
diff --git a/fastopenapi/openapi/generator.py b/fastopenapi/openapi/generator.py
@@ -132,7 +132,7 @@ def _apply_metadata_constraints(self, schema: dict, param_obj: BaseParam) -> Non
 
     def _apply_object_metadata(self, schema: dict, param_obj: BaseParam) -> None:
         """Apply object-level metadata"""
-        attrs = ["title", "description", "examples"]
+        attrs = ["title", "description", "example", "examples"]
         for attr in attrs:
             if hasattr(param_obj, attr):  # pragma: no cover
                 value = getattr(param_obj, attr)
@@ -389,6 +389,8 @@ def _add_parameter_metadata(
         if isinstance(param_obj, BaseParam):
             if param_obj.description:
                 param_info["description"] = param_obj.description
+            if hasattr(param_obj, "example") and param_obj.example is not None:
+                param_info["example"] = param_obj.example
             if hasattr(param_obj, "examples") and param_obj.examples:
                 param_info["examples"] = {
                     f"example_{i}": {"value": example}
diff --git a/tests/openapi/test_openapi_generator.py b/tests/openapi/test_openapi_generator.py
@@ -678,12 +678,27 @@ def test_schema_builder_apply_object_metadata_none_values(self):
         param_obj = Mock()
         param_obj.title = None
         param_obj.description = None
+        param_obj.example = None
         param_obj.examples = None
         param_obj.unknown = None
 
         builder._apply_object_metadata(schema, param_obj)
         assert schema == {}
 
+    def test_schema_builder_apply_object_metadata_with_example(self):
+        """Test applying object metadata with example value"""
+        builder = SchemaBuilder({}, threading.Lock())
+        schema = {}
+
+        param_obj = Mock()
+        param_obj.title = None
+        param_obj.description = None
+        param_obj.example = "laptop"
+        param_obj.examples = None
+
+        builder._apply_object_metadata(schema, param_obj)
+        assert schema == {"example": "laptop"}
+
     def test_schema_builder_apply_default_value_none_or_ellipsis(self):
         """Test applying None or ellipsis default values"""
         builder = SchemaBuilder({}, threading.Lock())
@@ -1066,6 +1081,17 @@ def test_parameter_processor_add_parameter_metadata_with_param_obj(self):
         assert "examples" in param_info
         assert param_info["deprecated"] is True
 
+    def test_parameter_processor_add_parameter_metadata_with_example(self):
+        """Test adding parameter metadata with example (singular)"""
+        processor = ParameterProcessor(self.generator.schema_builder)
+
+        param_info = {}
+        param_obj = Query(example="laptop")
+
+        processor._add_parameter_metadata(param_info, param_obj, "search")
+
+        assert param_info["example"] == "laptop"
+
     def test_parameter_processor_add_parameter_metadata_common_descriptions(self):
         """Test adding common parameter descriptions"""
         processor = ParameterProcessor(self.generator.schema_builder)
