OpenAPI and BaseTemplateController (#361)

* render_template now accepts kwargs
* fix openapi request bodies
* Fix testing

Author: tarsil

docs/en/docs/contrib/openapi.md

@@ -192,6 +192,33 @@ and **not** list `user_id` again under `in: query`.
 
     Always use distinct names for path and query parameters to avoid confusion. For example, use `user_id` in the path and `userIdQuery` in the query.
 
+### Request Bodies
+
+Use `request_body` in `@openapi(...)` to document inbound payloads.
+
+```python
+{!> ../../../docs_src/openapi/request_body.py !}
+```
+
+You can provide `request_body` as:
+
+* A model annotation (for example `Item`).
+* A list annotation (for example `list[Item]` or `[Item]`).
+* A JSON Schema dictionary.
+* A complete OpenAPI `requestBody` object (with `content`).
+
+For writing methods (`POST`, `PUT`, `PATCH`), the request body is now emitted even if you omit explicit `responses`.
+
+#### File Uploads (Multipart)
+
+For upload endpoints, model file fields as `bytes` and set `media_type` to `multipart/form-data`:
+
+```python
+{!> ../../../docs_src/openapi/request_body_upload.py !}
+```
+
+When the generated schema contains `format: binary`, Lilya defaults the request body media type to `multipart/form-data` if you don't set `media_type`.
+
 ---
 
 ### Response Models

docs/en/docs/release-notes.md

@@ -5,6 +5,14 @@ hide:
 
 # Release Notes
 
+## 0.24.3
+
+### Fixed
+
+- `lilya.contrib.openapi` now emits `requestBody` for writing methods (`POST`, `PUT`, `PATCH`) even when `responses` are not explicitly declared.
+- `@openapi(request_body=...)` now supports multipart upload request bodies correctly, including binary fields (`format: binary`) and proper `multipart/form-data` content generation.
+- `BaseTemplateController.render_template()` now accepts **kwargs.
+
 ## 0.24.2
 
 ### Added

docs_src/openapi/request_body.py

@@ -0,0 +1,12 @@
+from pydantic import BaseModel
+
+from lilya.contrib.openapi.decorator import openapi
+
+
+class CreateItemBody(BaseModel):
+    name: str
+    quantity: int
+
+
+@openapi(summary="Create item", request_body=CreateItemBody)
+async def create_item(request): ...

docs_src/openapi/request_body_upload.py

@@ -0,0 +1,17 @@
+from pydantic import BaseModel
+
+from lilya.contrib.openapi.decorator import openapi
+from lilya.enums import MediaType
+
+
+class UploadBody(BaseModel):
+    user: str
+    file: bytes
+
+
+@openapi(
+    summary="Upload file",
+    request_body=UploadBody,
+    media_type=MediaType.MULTIPART,
+)
+async def upload_file(request): ...

lilya/__init__.py

@@ -1 +1 @@
-__version__ = "0.24.2"
+__version__ = "0.24.3"

lilya/contrib/openapi/decorator.py

@@ -1,7 +1,9 @@
 import inspect
 from collections.abc import Callable, Sequence
 from functools import lru_cache, wraps
-from typing import Annotated, Any, cast, get_args, get_origin
+from typing import Annotated, Any, cast, get_origin
+
+from pydantic import TypeAdapter
 
 from lilya._internal._responses import BaseHandler
 from lilya._utils import is_function
@@ -12,6 +14,91 @@
 from lilya.contrib.security.base import SecurityBase, SecurityScheme
 
 SUCCESSFUL_RESPONSE = "Successful response"
+DEFAULT_REQUEST_MEDIA_TYPE = "application/json"
+MULTIPART_REQUEST_MEDIA_TYPE = "multipart/form-data"
+REQUEST_BODY_SCHEMA_KEYS = {
+    "$ref",
+    "allOf",
+    "anyOf",
+    "format",
+    "items",
+    "oneOf",
+    "properties",
+    "required",
+    "type",
+}
+
+
+def _is_openapi_request_body_dict(value: Any) -> bool:
+    """
+    Determine whether a value is already an OpenAPI ``requestBody`` object.
+    """
+    return isinstance(value, dict) and "content" in value and isinstance(value["content"], dict)
+
+
+def _is_json_schema_dict(value: Any) -> bool:
+    """
+    Determine whether a dictionary looks like a JSON Schema object.
+    """
+    return isinstance(value, dict) and any(key in value for key in REQUEST_BODY_SCHEMA_KEYS)
+
+
+def _schema_contains_binary_format(schema: Any) -> bool:
+    """
+    Recursively detect whether a JSON Schema contains ``format: binary``.
+    """
+    if isinstance(schema, dict):
+        if schema.get("format") == "binary":
+            return True
+        return any(_schema_contains_binary_format(value) for value in schema.values())
+    if isinstance(schema, list):
+        return any(_schema_contains_binary_format(value) for value in schema)
+    return False
+
+
+def _build_request_body_metadata(
+    request_body: Any | None,
+    media_type: str | None,
+) -> dict[str, Any]:
+    """
+    Normalize the ``request_body`` decorator input into an OpenAPI ``requestBody`` object.
+
+    Supported forms are:
+    - A Python annotation or model (e.g. ``MyModel`` or ``list[MyModel]``).
+    - A single-item list/tuple shorthand (e.g. ``[MyModel]``).
+    - A JSON Schema dictionary.
+    - A complete OpenAPI ``requestBody`` dictionary containing ``content``.
+    """
+    if request_body is None:
+        return {}
+
+    if _is_openapi_request_body_dict(request_body):
+        return request_body  # type: ignore
+
+    if _is_json_schema_dict(request_body):
+        schema = request_body
+    else:
+        if isinstance(request_body, (list, tuple)):
+            if len(request_body) != 1:
+                raise ValueError(
+                    "Request body list/tuple representation accepts a single model only. "
+                    "Example: request_body=[MyModel]."
+                )
+            annotation: Any = list[request_body[0]]  # type: ignore
+        elif get_origin(request_body) in (list, tuple, Sequence):
+            annotation = request_body
+        else:
+            annotation = request_body
+
+        converted_annotation = convert_annotation_to_pydantic_model(annotation)
+        schema = TypeAdapter(converted_annotation).json_schema()
+
+    selected_media_type = media_type or (
+        MULTIPART_REQUEST_MEDIA_TYPE
+        if _schema_contains_binary_format(schema)
+        else DEFAULT_REQUEST_MEDIA_TYPE
+    )
+    return {"content": {selected_media_type: {"schema": schema}}}
 
 
 class OpenAPIMethod:
@@ -37,6 +124,9 @@ def wrapper(*args: Any, **kwargs: Any) -> Any:
 
 @lru_cache
 def get_signature(func: Callable[..., Any]) -> inspect.Signature:
+    """
+    Cache and return the function signature used by the response handler wrapper.
+    """
     return inspect.Signature.from_callable(func)
 
 
@@ -77,8 +167,8 @@ def openapi(
         str | None,
         Doc(
             """
-            The string indicating the content media type of the handler (e.g. "application/json").
-            Used for OpenAPI.
+            The media type used for the OpenAPI request body when `request_body` is provided
+            (e.g. "application/json" or "multipart/form-data").
             """
         ),
     ] = None,
@@ -152,7 +242,9 @@ def openapi(
         Any | None,
         Doc(
             """
-            Overridable request body for the payload to be sent.
+            Overridable request body definition.
+            It accepts a model annotation, a JSON Schema object, or a complete OpenAPI
+            requestBody object (with `content`).
             """
         ),
     ] = None,
@@ -169,6 +261,9 @@ def wrapper(*args: Any, **kwargs: Any) -> Any:
             return handler.handle_response(func, other_signature=signature)
 
         def response_models(responses: dict[int, OpenAPIResponse] | None = None) -> Any:
+            """
+            Convert OpenAPI response model declarations into internal response metadata.
+            """
             responses: dict[int, ResponseParam] = {} if responses is None else responses  # type: ignore
 
             if responses:
@@ -191,6 +286,9 @@ def response_models(responses: dict[int, OpenAPIResponse] | None = None) -> Any:
         def query_strings(
             query_dict: dict[str, Query] | dict[str, Any] | set[str] | None = None,
         ) -> dict[str, Query]:
+            """
+            Normalize query parameter declarations into ``Query`` instances.
+            """
             if query_dict is None:
                 return {}
 
@@ -211,40 +309,12 @@ def query_strings(
                 "Query must be a dict or set or a dict of key-pair value of str and Query"
             )
 
-        def get_request_body(
-            request_body: Any | None = None,
-        ) -> Any:
-            if request_body is None:
-                return {}
-
-            if isinstance(request_body, (list, tuple)):
-                model: Any = request_body[0]
-                annotation = list[model]
-            elif get_origin(request_body) is list:
-                annotation = request_body
-            else:
-                annotation = request_body
-
-            # 2. Convert to Pydantic model (handles encodings/nested types)
-            converted_annotation = convert_annotation_to_pydantic_model(annotation)
-
-            # 3. Generate Schema
-            # We must check if it's a list/sequence again on the converted annotation
-            origin = get_origin(converted_annotation)
-
-            if origin in (list, tuple, Sequence):
-                # It is a list: Extract args and get schema of the inner model
-                args = get_args(converted_annotation)
-                # Return as a list containing the schema, matching Lilya's expectation
-                body_fields = [args[0].model_json_schema()]
-            else:
-                # It is a single model: Get schema directly
-                body_fields = converted_annotation.model_json_schema()
-            return body_fields
-
         def handle_security_requirement(
             security_requirements: Sequence[Any] | None,
         ) -> list[dict[str, Any]] | None:
+            """
+            Normalize security requirements into OpenAPI security scheme declarations.
+            """
             security_schemes = []
             security_definitions: dict[str, dict[str, Any]] = {}
 
@@ -291,7 +361,7 @@ def handle_security_requirement(
             "query": query_strings(query) or {},
         }
 
-        body_fields = get_request_body(request_body)
+        body_fields = _build_request_body_metadata(request_body, media_type)
         wrapper.openapi_meta["request_body"] = body_fields
 
         if is_function(func) and not inspect.ismethod(func):

lilya/contrib/openapi/utils.py

@@ -12,8 +12,38 @@
 from lilya.controllers import Controller
 from lilya.enums import HTTPMethod
 
+DEFAULT_REQUEST_MEDIA_TYPE = "application/json"
+
+
+def _normalize_request_body_operation(
+    request_body: Any,
+    media_type: str | None = None,
+) -> dict[str, Any]:
+    """
+    Normalize request body metadata into a valid OpenAPI ``requestBody`` object.
+
+    This keeps backward compatibility with older metadata shapes where only a
+    plain schema (or a one-item list for array schema) was stored.
+    """
+    if not request_body:
+        return {}
+
+    if isinstance(request_body, dict) and "content" in request_body:
+        return request_body
+
+    if isinstance(request_body, list):
+        schema_payload = {"type": "array", "items": request_body[0]}
+    else:
+        schema_payload = request_body
+
+    request_media_type = media_type or DEFAULT_REQUEST_MEDIA_TYPE
+    return {"content": {request_media_type: {"schema": schema_payload}}}
+
 
 def extract_http_methods_from_endpoint(cls: type) -> list[str]:
+    """
+    Extract HTTP method names implemented by a controller class.
+    """
     return [
         method.upper()
         for method in HTTPMethod.to_list()
@@ -37,6 +67,9 @@ def get_openapi(
     license: dict[str, Any] | None = None,
     webhooks: Sequence[Any] | None = None,
 ) -> dict[str, Any]:
+    """
+    Generate the OpenAPI specification dictionary for a Lilya application.
+    """
     info = {
         "title": title,
         "version": version,
@@ -158,6 +191,14 @@ def _gather_routes(routes_list: Sequence[Any], prefix: str) -> list[tuple[str, A
                 else:
                     operation["parameters"].append(query_param)
 
+            if m_lower in WRITING_METHODS:
+                request_body = _normalize_request_body_operation(
+                    request_body=meta.get("request_body", {}),
+                    media_type=meta.get("media_type"),
+                )
+                if request_body:
+                    operation["requestBody"] = request_body
+
             responses_obj = {}
             seen_responses = meta.get("responses", {})
             schema_generator = GenerateJsonSchema(ref_template=REF_TEMPLATE)
@@ -192,18 +233,6 @@ def _gather_routes(routes_list: Sequence[Any], prefix: str) -> list[tuple[str, A
                 for name, schema_def in definitions.items():
                     spec["components"]["schemas"][name] = schema_def  # type: ignore
 
-                # For the request body
-                request_body = meta.get("request_body", {})
-                if m_lower in WRITING_METHODS and request_body:
-                    if isinstance(request_body, list):
-                        schema_payload = {"type": "array", "items": request_body[0]}
-                    else:
-                        schema_payload = request_body
-
-                    operation["requestBody"] = {
-                        "content": {"application/json": {"schema": schema_payload}}
-                    }
-
                 for status_code_int, response in seen_responses.items():
                     status_code = str(status_code_int)
                     desc = getattr(response, "description", "") or ""

lilya/templating/controllers.py

@@ -213,7 +213,7 @@ async def get_context_data(self, request: Request, **kwargs: Any) -> dict:
         return context
 
     async def render_template(
-        self, request: Request, context: dict[str, Any] | None = None
+        self, request: Request, context: dict[str, Any] | None = None, **kwargs: Any
     ) -> HTMLResponse:
         """
         Renders the specified template with the given context into an HTMLResponse.

tests/app_settings/test_settings.py

@@ -75,7 +75,7 @@ def test_dict_default():
         "ptpython_config_file": "~/.config/ptpython/config.py",
         "debug": False,
         "environment": "production",
-        "version": "0.24.2",
+        "version": settings.version,
         "include_in_schema": True,
         "default_route_pattern": "route_patterns",
         "enforce_return_annotation": False,