csrd-versioning 0.1.0__py3-none-any.whl

csrd/versioning/swagger_plugins/file_upload/_body_factory.py

@@ -0,0 +1,121 @@
+"""Annotate Pydantic models for use alongside ``UploadFile``.
+
+Provides :func:`file_upload_body` which builds a three-layer ``Annotated``
+type that preserves model fields in OpenAPI, attaches examples for the
+Swagger UI plugin, and aliases the form field with the model name.
+
+Also provides :func:`unwrap_json_schema` which fixes Pydantic's
+``Json[Model]`` wrapping so Swagger UI renders the model's fields instead
+of a plain string input.
+"""
+
+from typing import Annotated
+
+from pydantic import BaseModel
+from pydantic.json_schema import GetJsonSchemaHandler, JsonSchemaValue
+from pydantic_core import CoreSchema
+
+
+def unwrap_json_schema(example: dict | None = None):
+    """Pydantic JSON schema override that unwraps ``contentSchema``.
+
+    When a field is typed as ``Json[Model]``, Pydantic wraps the schema
+    in a ``contentSchema`` envelope.  Swagger UI doesn't understand that
+    wrapper and renders a plain string input.  This override inlines the
+    inner schema so Swagger renders the model's fields directly.
+    """
+
+    class _NotAsJson:
+        @classmethod
+        def __get_pydantic_json_schema__(
+            cls, core_schema: CoreSchema, handler: GetJsonSchemaHandler
+        ) -> JsonSchemaValue:
+            json_schema = handler(core_schema)
+            return {
+                **(json_schema.get("contentSchema", json_schema)),
+                **({"example": example} if example is not None else {}),
+            }
+
+    return _NotAsJson
+
+
+def file_upload_body(
+    model: type[BaseModel],
+    examples: dict,
+    default_key: str | None = None,
+    name: str | None = None,
+):
+    """Annotate a Pydantic model for use alongside ``UploadFile``.
+
+    When a FastAPI endpoint accepts both a JSON body **and** a file
+    upload, the request must be sent as ``multipart/form-data``.
+    FastAPI requires the JSON portion to be wrapped in ``Json[...]``
+    and sent as a form field, but that breaks Swagger UI's schema
+    rendering and example dropdown.  This factory builds the correct
+    three-layer ``Annotated`` type that:
+
+    1. Preserves the model's fields in the OpenAPI schema
+       (via :func:`unwrap_json_schema`)
+    2. Attaches ``openapi_examples`` so the file upload plugin can
+       render them in Swagger UI
+    3. Aliases the form field with the model name (camelCase)
+
+    Parameters
+    ----------
+    model:
+        The Pydantic model class for the JSON body.
+    examples:
+        A dict of ``{key: Example(...)}`` for the Swagger UI dropdown.
+    default_key:
+        Key in *examples* whose ``value`` is shown as the inline
+        schema example before the user opens the dropdown.  ``None``
+        omits the inline example.
+    name:
+        Schema name for the generated body wrapper in OpenAPI's
+        ``components/schemas``.  If ``None`` (default), derived from
+        the model class name (e.g. ``DocumentRequest`` →
+        ``DocumentRequestBody``).  The schema patcher renames the
+        auto-generated ``Body_*`` key to this value.
+
+    Returns
+    -------
+    type
+        An ``Annotated`` type suitable for use as an endpoint parameter.
+
+    Example
+    -------
+    ::
+
+        from fastapi.openapi.models import Example
+
+        my_examples = {
+            "basic": Example(
+                summary="Basic request",
+                value={"name": "Acme"},
+            ),
+        }
+        MyRequest = file_upload_body(MyModel, my_examples, "basic")
+
+        @router.post("/upload")
+        async def upload(
+            request: MyRequest,
+            file: Optional[UploadFile] = None,
+        ):
+            ...
+    """
+    from fastapi import Body, Form
+    from pydantic import Json
+
+    schema_name = name or f"{model.__name__}Body"
+    field_alias = model.__name__[0].lower() + model.__name__[1:]
+    default_value = dict(examples[default_key]).get("value") if default_key else None
+    body = Annotated[model, Body(openapi_examples=examples)]  # type: ignore[valid-type]
+    return Annotated[  # type: ignore[return-value]
+        Json[body],  # type: ignore[valid-type,misc]
+        unwrap_json_schema(default_value),
+        Form(
+            alias=field_alias,
+            openapi_examples=examples,
+            json_schema_extra={"x-schema-name": schema_name},
+        ),
+    ]

csrd/versioning/swagger_plugins/file_upload/_schema_patcher.py

@@ -0,0 +1,165 @@
+"""Auto-detect and inject multipart/form-data examples into OpenAPI schemas.
+
+This module provides the schema patcher for the file upload examples plugin.
+It auto-discovers routes whose endpoint parameters use
+``Form(openapi_examples=...)`` and injects the examples at the media-type
+level where Swagger UI can render them via the companion JS plugin.
+"""
+
+import json
+import typing
+
+from fastapi import FastAPI
+
+from .._base import SchemaContext
+
+
+def _attr(obj: object, name: str, default: object = None) -> object:
+    """Read *name* from an object (attr) or dict (key).
+
+    FastAPI's ``Example(...)`` returns a plain dict, not an object, so
+    we need to handle both access patterns.
+    """
+    try:
+        return getattr(obj, name)
+    except AttributeError:
+        return obj.get(name, default) if isinstance(obj, dict) else default
+
+
+def _discover(app: FastAPI) -> dict[str, dict]:
+    """Find routes whose endpoint params have ``Form(openapi_examples=...)``.
+
+    Returns a dict mapping route paths to dicts with ``examples`` and
+    an optional ``schema_name`` derived from the ``x-schema-name``
+    marker set by :func:`file_upload_body`.
+    """
+    from fastapi.params import Body, Form
+    from fastapi.routing import APIRoute
+
+    result: dict[str, dict] = {}
+    for route in app.routes:
+        if not isinstance(route, APIRoute):
+            continue
+        examples: dict = {}
+        schema_name: str | None = None
+        try:
+            hints = typing.get_type_hints(route.endpoint, include_extras=True)
+        except Exception:
+            continue
+        for hint in hints.values():
+            if not hasattr(hint, "__metadata__"):
+                continue
+            for meta in hint.__metadata__:
+                if isinstance(meta, (Form, Body)):
+                    ex = getattr(meta, "openapi_examples", None)
+                    if ex:
+                        examples.update(ex)
+                    extra = getattr(meta, "json_schema_extra", None)
+                    if isinstance(extra, dict) and "x-schema-name" in extra:
+                        schema_name = extra["x-schema-name"]
+        if examples:
+            result[route.path] = {
+                "examples": examples,
+                "schema_name": schema_name,
+            }
+    return result
+
+
+def _inject(schema: dict, path_data: dict[str, dict], prefix: str = "") -> None:
+    """Mutate *schema* in-place, adding examples and renaming schemas.
+
+    Supports POST, PUT, and PATCH methods.  Route paths discovered from
+    the sub-app are un-prefixed (e.g. ``/documents``), but the OpenAPI
+    schema may already have the normalised prefix applied
+    (e.g. ``/api/documents``).  We check both variants.
+    """
+    schema_paths = schema.get("paths", {})
+    renames: dict[str, str] = {}  # old_name → new_name
+    for route_path, data in path_data.items():
+        examples = data["examples"]
+        schema_name = data.get("schema_name")
+        # The sub-app route is un-prefixed; the schema may be prefixed.
+        if route_path in schema_paths:
+            schema_path = route_path
+        elif prefix and f"{prefix}{route_path}" in schema_paths:
+            schema_path = f"{prefix}{route_path}"
+        else:
+            continue
+        for method in ("post", "put", "patch"):
+            content = (
+                schema_paths[schema_path].get(method, {}).get("requestBody", {}).get("content", {})
+            )
+            mp = content.get("multipart/form-data")
+            if mp is None:
+                continue
+            mp["examples"] = {
+                key: {
+                    "summary": _attr(ex, "summary", key),
+                    "description": _attr(ex, "description", ""),
+                    "value": json.dumps(_attr(ex, "value"), indent=2, sort_keys=True),
+                }
+                for key, ex in examples.items()
+            }
+            # Collect rename: resolve the $ref to find the old schema key
+            if schema_name:
+                ref = mp.get("schema", {}).get("$ref", "")
+                if ref.startswith("#/components/schemas/"):
+                    old_name = ref.split("/")[-1]
+                    if old_name != schema_name:
+                        renames[old_name] = schema_name
+    # Apply renames: update schema keys and all $ref pointers
+    if renames:
+        _rename_schemas(schema, renames)
+
+
+def _rename_schemas(schema: dict, renames: dict[str, str]) -> None:
+    """Rename schema keys in ``components/schemas`` and update all ``$ref``s.
+
+    When multiple Body wrappers map to the same target name (e.g. two
+    routes sharing the same ``file_upload_body`` type), a numeric suffix
+    is appended to avoid collisions (``DocumentRequestBody2``, etc.).
+    """
+    schemas = schema.get("components", {}).get("schemas", {})
+    used: set[str] = set()
+    for old_name, desired_name in renames.items():
+        if old_name not in schemas:
+            continue
+        new_name = desired_name
+        if new_name in schemas or new_name in used:
+            counter = 2
+            while f"{desired_name}{counter}" in schemas or f"{desired_name}{counter}" in used:
+                counter += 1
+            new_name = f"{desired_name}{counter}"
+        used.add(new_name)
+        schemas[new_name] = schemas.pop(old_name)
+        schemas[new_name]["title"] = new_name
+        _update_refs(
+            schema,
+            f"#/components/schemas/{old_name}",
+            f"#/components/schemas/{new_name}",
+        )
+
+
+def _update_refs(obj: object, old_ref: str, new_ref: str) -> None:
+    """Recursively replace ``$ref`` values throughout the schema."""
+    if isinstance(obj, dict):
+        if obj.get("$ref") == old_ref:
+            obj["$ref"] = new_ref
+        for v in obj.values():
+            _update_refs(v, old_ref, new_ref)
+    elif isinstance(obj, list):
+        for item in obj:
+            _update_refs(item, old_ref, new_ref)
+
+
+def patch_file_upload_examples(schema: dict, ctx: SchemaContext) -> dict:
+    """Schema patcher: discover file-upload routes and inject examples.
+
+    This is the transformer function passed as ``schema_patcher`` in the
+    plugin's :meth:`contribute` return value.  It follows the
+    ``(schema, ctx) -> schema`` transformer pattern.
+    """
+    path_data = _discover(ctx.app)
+    if path_data:
+        _inject(schema, path_data, prefix=ctx.prefix)
+    return schema

csrd/versioning/swagger_plugins/file_upload/file_upload_plugin.css

@@ -0,0 +1,181 @@
+/* ── File Upload Examples Plugin CSS ─────────────────────────────── */
+
+/* Dropdown uses native .examples-select (margin-bottom: .75em built in) */
+
+/* Stable wrapper for post-click dropdown + description */
+.swagger-ui .multipart-postclick-controls {
+  padding: 0;
+}
+
+/* Post-click tabs (Example Value | Schema) inside the controls block */
+.swagger-ui .multipart-postclick-controls > .tab {
+  margin-top: .75em;
+  padding-bottom: 1em;
+}
+
+/* Extra gap in the preview (before "Try it out") where tab bar is tighter */
+.swagger-ui .multipart-body-preview .examples-select {
+  margin-bottom: .75em;
+}
+
+/* The preview tab bar needs its own margins (native .tab gets them from context) */
+.swagger-ui .multipart-body-preview > .tab {
+  margin-top: .75em;
+  padding-bottom: 1em;
+}
+
+/* Preview body container — inherits padding from .opblock-description-wrapper */
+.swagger-ui .multipart-body-preview {
+  padding: 0;
+}
+
+/* File upload placeholder in the preview (before "Try it out") */
+.swagger-ui .multipart-preview-file {
+  margin-top: 1.5em;
+}
+
+/* Required tag on pre-click file row — matches Swagger UI native styling */
+.swagger-ui .multipart-preview-file .multipart-required-tag {
+  color: var(--dark-text-warn);
+  font-size: 10px;
+  font-weight: 700;
+  padding: 5px;
+  position: relative;
+  top: -6px;
+}
+.swagger-ui .multipart-preview-file .multipart-required-star {
+  color: var(--dark-text-warn);
+}
+
+/* Example Description — uses native .example__section (margin-top: 1.5em built in) */
+.swagger-ui .multipart-preview-description p {
+  color: #3b4151;
+  font-size: 14px;
+  font-family: sans-serif;
+  margin: .25em 0 0;
+}
+body.dark .swagger-ui .multipart-preview-description p {
+  color: #e4e6e6;
+}
+
+
+/* Strip doubled top padding from the table container */
+.swagger-ui .multipart-form-table {
+  padding-top: 0 !important;
+}
+
+/* Post-click wrapper: flex column so we can reorder description before file row */
+.swagger-ui .multipart-examples-wrapper {
+  display: flex;
+  flex-direction: column;
+}
+
+/* Order the flattened flex children:
+   controls (0) → form/schema (1) → description (2) → file row (3) → execute (4) */
+.swagger-ui .multipart-postclick-controls { order: 0; }
+.swagger-ui .multipart-examples-wrapper .opblock-section-header { order: 1; }
+.swagger-ui .multipart-form-table tr { order: 1; }
+.swagger-ui .multipart-examples-wrapper .multipart-schema-pane { order: 1; width: 100%; }
+.swagger-ui .multipart-postclick-description { order: 2; padding: 0; }
+.swagger-ui .multipart-form-table tr:has(input[type="file"]) { order: 3; }
+.swagger-ui .multipart-examples-wrapper .execute-wrapper { order: 4; }
+
+/* Strip inner table padding — the .table-container wrapper provides it */
+.swagger-ui .multipart-form-table table {
+  display: block;
+  width: 100%;
+  padding: 0;
+}
+
+.swagger-ui .multipart-form-table tbody,
+.swagger-ui .multipart-form-table tr {
+  display: block;
+  width: 100%;
+}
+
+/* File row: lay out name + picker horizontally, push to end via order */
+.swagger-ui .multipart-form-table tr:has(input[type="file"]) {
+  order: 3;
+  display: flex;
+  align-items: flex-start;
+  gap: 20px;
+  margin-top: 18px;
+}
+
+/* Use display:contents on intermediate wrappers so flex order reaches the rows */
+.swagger-ui .multipart-examples-wrapper > .opblock-body,
+.swagger-ui .multipart-examples-wrapper .opblock-section-request-body,
+.swagger-ui .multipart-examples-wrapper .opblock-description-wrapper,
+.swagger-ui .multipart-examples-wrapper .multipart-form-table,
+.swagger-ui .multipart-examples-wrapper .multipart-form-table table,
+.swagger-ui .multipart-examples-wrapper .multipart-form-table tbody {
+  display: contents;
+}
+
+/* Hide the native "required" badge on the section header — the plugin
+   shows required at the field level instead. */
+.swagger-ui .opblock-body:has(.multipart-examples-wrapper) .opblock-section-header label {
+  display: none;
+}
+.swagger-ui .opblock-body:has(.multipart-body-preview) .opblock-section-header label {
+  display: none;
+}
+
+/* Hide the column headers (Name | Description) */
+.swagger-ui .multipart-form-table thead {
+  display: none;
+}
+
+/* Hide all name cells by default */
+.swagger-ui .multipart-form-table .parameters-col_name {
+  display: none;
+}
+
+/* Make description cells fill the full width */
+.swagger-ui .multipart-form-table .parameters-col_description {
+  display: block;
+  width: 100% !important;
+  max-width: none;
+  margin-bottom: 0;
+}
+
+.swagger-ui .multipart-form-table tr:has(input[type="file"]) > .parameters-col_name {
+  display: block;
+  width: auto !important;
+  flex-shrink: 0;
+  padding-bottom: 0;
+}
+
+/* ── Dark mode overrides ─────────────────────────────────────────── */
+
+body.dark .swagger-ui .examples-select__section-label,
+body.dark .swagger-ui .example__section-header,
+body.dark .swagger-ui .example__section {
+  color: var(--dark-text-color) !important;
+}
+
+body.dark .swagger-ui .multipart-body-preview .highlight-code pre {
+  background-color: var(--dark-bg-color-2);
+  color: var(--dark-text-color);
+}
+
+body.dark .swagger-ui .multipart-body-preview .parameter__name {
+  color: var(--dark-text-color);
+}
+
+body.dark .swagger-ui .multipart-body-preview .parameter__type {
+  color: var(--dark-text-color-2);
+}
+
+body.dark .swagger-ui .multipart-examples-wrapper .multipart-form-table .parameters-col_description textarea {
+  background-color: var(--dark-bg-color-2);
+  color: var(--dark-text-color);
+}
+
+/* Per-verb dark mode blocks for the preview pane */
+body.dark .swagger-ui .opblock.opblock-post .multipart-body-preview,
+body.dark .swagger-ui .opblock.opblock-put .multipart-body-preview,
+body.dark .swagger-ui .opblock.opblock-patch .multipart-body-preview {
+  background-color: inherit;
+  color: var(--dark-text-color);
+}