fastapi-docs-plus 1.0.0__py3-none-any.whl

fastapi_docs_plus/pre_request.py

@@ -0,0 +1,145 @@
+from __future__ import annotations
+
+import inspect
+from dataclasses import dataclass, field
+from typing import Any, Awaitable, Callable
+from urllib.parse import unquote_plus, urlsplit
+
+from starlette.routing import Match
+
+
+@dataclass
+class PreRequestContext:
+    """Context for a single Try-it-out request that is about to be sent.
+
+    Modify ``headers`` or ``query`` directly to affect the outgoing
+    request. All other fields are read-only.
+
+    Attributes:
+        method: Uppercase HTTP method (e.g. ``"GET"``, ``"POST"``).
+        url: The full request URL.
+        path: The path component of the URL.
+        headers: Mutable mapping of request headers. Modifications are
+            reflected in the actual request.
+        query: Mutable mapping of query-string parameters (URL-decoded).
+            Modifications are re-encoded for the actual request.
+        env: Environment variables passed from the frontend, including
+            ``identity`` and any extra environment JSON.
+        route_path: The matched route template (e.g.
+            ``"/shops/{shop_id}"``), or ``None`` if no route matched.
+        operation_id: The ``operation_id`` of the matched route, or the
+            route name, or ``None``.
+        path_params: Path parameters extracted from the URL (e.g.
+            ``{"shop_id": "shop-0042"}``).
+    """
+
+    method: str
+    url: str
+    path: str
+    headers: dict[str, str]
+    query: dict[str, str]
+    env: dict[str, Any] = field(default_factory=dict)
+    route_path: str | None = None
+    operation_id: str | None = None
+    path_params: dict[str, Any] = field(default_factory=dict)
+
+    @property
+    def identity(self) -> str | None:
+        """The user-selected identity from the top-bar dropdown, if any."""
+        value = self.env.get("identity")
+        return value if isinstance(value, str) and value else None
+
+
+PreRequestHook = Callable[[PreRequestContext], None | Awaitable[None]]
+"""Signature for a pre-request hook function.
+
+A hook receives a :class:`PreRequestContext` and may modify
+``ctx.headers`` and ``ctx.query``. It can be synchronous or
+asynchronous.
+"""
+
+
+def match_route(app, method: str, path: str):
+    """Resolve the route matching a given HTTP method and path.
+
+    Returns a ``(route, path_params)`` tuple by scanning
+    ``app.routes``. Prefers a ``FULL`` match over ``PARTIAL``.
+
+    Args:
+        app: The FastAPI application instance.
+        method: HTTP method (e.g. ``"GET"``).
+        path: The URL path to match.
+
+    Returns:
+        ``(route, path_params)`` where *route* is the matched
+        ``APIRoute`` (or ``None``) and *path_params* is a dict of
+        extracted path parameters.
+    """
+    scope = {
+        "type": "http",
+        "method": method.upper(),
+        "path": path,
+        "root_path": "",
+        "headers": [],
+        "query_string": b"",
+    }
+    partial = None
+    for route in app.routes:
+        match, child_scope = route.matches(scope)
+        if match == Match.FULL:
+            return route, child_scope.get("path_params") or {}
+        if match == Match.PARTIAL and partial is None:
+            partial = (route, child_scope.get("path_params") or {})
+    return partial if partial else (None, {})
+
+
+def build_context(app, *, method: str, url: str, headers: dict[str, str], env: dict[str, Any]) -> PreRequestContext:
+    """Build a :class:`PreRequestContext` from the frontend's pre-request payload.
+
+    Parses the URL, extracts query parameters (URL-decoded), and
+    resolves the matched route and path params.
+
+    Args:
+        app: The FastAPI application instance.
+        method: HTTP method.
+        url: Full request URL.
+        headers: Request headers from the frontend.
+        env: Environment variables from the frontend (identity, extra
+            env JSON, etc.).
+    """
+    parts = urlsplit(url)
+    query: dict[str, str] = {}
+    for pair in parts.query.split("&"):
+        if not pair:
+            continue
+        key, _, value = pair.partition("=")
+        query[unquote_plus(key)] = unquote_plus(value)
+
+    route, path_params = match_route(app, method, parts.path)
+    return PreRequestContext(
+        method=method.upper(),
+        url=url,
+        path=parts.path,
+        headers=dict(headers),
+        query=query,
+        env=env,
+        route_path=getattr(route, "path", None),
+        operation_id=getattr(route, "operation_id", None) or getattr(route, "name", None),
+        path_params=path_params,
+    )
+
+
+async def run_hooks(hooks: list[PreRequestHook], ctx: PreRequestContext) -> None:
+    """Execute a list of pre-request hooks in registration order.
+
+    Hooks share the same :class:`PreRequestContext` instance.
+    Supports both synchronous and asynchronous callables.
+
+    Args:
+        hooks: List of pre-request hook callables.
+        ctx: The request context to pass to each hook.
+    """
+    for hook in hooks:
+        result = hook(ctx)
+        if inspect.isawaitable(result):
+            await result

fastapi_docs_plus/schema_utils.py

@@ -0,0 +1,174 @@
+from __future__ import annotations
+
+from typing import Any
+
+# "title" carries almost no signal for the LLM (it often duplicates
+# the field name), so dropping it saves a significant number of tokens.
+_DROP_KEYS = {"title"}
+_INLINED_CONTAINERS = ("$defs", "definitions")
+_MAP_KEYS = ("properties", "patternProperties")
+_SINGLE_KEYS = ("items", "additionalProperties", "not", "contains")
+_LIST_KEYS = ("anyOf", "oneOf", "allOf", "prefixItems")
+_PARAM_KEYS = ("name", "in", "required", "description", "schema", "example", "examples")
+
+
+def _resolve_pointer(ref: str, root: dict) -> dict | None:
+    if not ref.startswith("#/"):
+        return None
+    node: Any = root
+    for raw in ref[2:].split("/"):
+        part = raw.replace("~1", "/").replace("~0", "~")
+        if isinstance(node, list):
+            try:
+                node = node[int(part)]
+            except (ValueError, IndexError):
+                return None
+        elif isinstance(node, dict) and part in node:
+            node = node[part]
+        else:
+            return None
+    return node if isinstance(node, dict) else None
+
+
+def flatten_schema(
+    schema: Any,
+    root: dict,
+    *,
+    max_depth: int = 4,
+    _depth: int = 0,
+    _stack: tuple[str, ...] = (),
+) -> Any:
+    """Inline ``$ref`` pointers and truncate recursive / over-deep structures.
+
+    Produces a self-contained schema that can be fed directly to an LLM.
+
+    Args:
+        schema: The JSON Schema fragment to process.
+        root: The root OpenAPI document (used for ``$ref`` resolution).
+        max_depth: Maximum nesting depth before truncation.
+        _depth: Internal recursion depth tracker.
+        _stack: Internal ``$ref`` chain for cycle detection.
+
+    Returns:
+        A flattened, self-contained schema dict.
+    """
+    if not isinstance(schema, dict):
+        return schema
+
+    ref = schema.get("$ref")
+    if isinstance(ref, str):
+        name = ref.rsplit("/", 1)[-1]
+        if ref in _stack:
+            return {"type": "object", "description": f"Recursive reference {name}; generate one level only"}
+        target = _resolve_pointer(ref, root)
+        if target is None:
+            return {"type": "object", "description": f"Unresolvable reference {ref}"}
+        sibling = {k: v for k, v in schema.items() if k != "$ref"}
+        return flatten_schema(
+            {**target, **sibling},
+            root,
+            max_depth=max_depth,
+            _depth=_depth,
+            _stack=_stack + (ref,),
+        )
+
+    if _depth >= max_depth:
+        return {"type": schema.get("type", "object"), "description": "Reached max depth; free-form values allowed"}
+
+    out: dict[str, Any] = {}
+    for key, value in schema.items():
+        if key in _DROP_KEYS or key in _INLINED_CONTAINERS:
+            continue
+        kwargs = {"max_depth": max_depth, "_stack": _stack}
+        if key in _MAP_KEYS and isinstance(value, dict):
+            out[key] = {
+                k: flatten_schema(v, root, _depth=_depth + 1, **kwargs) for k, v in value.items()
+            }
+        elif key in _SINGLE_KEYS and isinstance(value, dict):
+            out[key] = flatten_schema(value, root, _depth=_depth + 1, **kwargs)
+        elif key in _LIST_KEYS and isinstance(value, list):
+            out[key] = [flatten_schema(v, root, _depth=_depth, **kwargs) for v in value]
+        else:
+            out[key] = value
+    return out
+
+
+def _pick_body_content(request_body: dict) -> tuple[str | None, dict | None]:
+    content = request_body.get("content") or {}
+    if not content:
+        return None, None
+    for media_type in content:
+        if "json" in media_type:
+            return media_type, content[media_type]
+    media_type = next(iter(content))
+    return media_type, content[media_type]
+
+
+def build_operation_spec(openapi: dict, path: str, method: str, *, max_depth: int = 4) -> dict:
+    """Extract a self-contained description of a single OpenAPI operation.
+
+    The result is suitable for sending to an LLM to generate parameter
+    values.
+
+    Args:
+        openapi: The full OpenAPI document (``app.openapi()``).
+        path: The URL path (e.g. ``"/users/{id}"``).
+        method: The HTTP method (e.g. ``"get"``, ``"post"``).
+        max_depth: Maximum schema nesting depth.
+
+    Returns:
+        A dict with keys ``method``, ``path``, ``summary``,
+        ``description``, ``parameters``, and optionally
+        ``requestBody`` and ``businessHint``.
+
+    Raises:
+        KeyError: If the path or operation does not exist in the
+            OpenAPI document.
+    """
+    path_item = (openapi.get("paths") or {}).get(path)
+    if not isinstance(path_item, dict):
+        raise KeyError(f"Path not found in OpenAPI: {path}")
+    operation = path_item.get(method.lower())
+    if not isinstance(operation, dict):
+        raise KeyError(f"Operation not found in OpenAPI: {method.upper()} {path}")
+
+    parameters = []
+    shared = path_item.get("parameters") or []
+    own = operation.get("parameters") or []
+    for raw in [*shared, *own]:
+        if not isinstance(raw, dict):
+            continue
+        if isinstance(raw.get("$ref"), str):
+            resolved = _resolve_pointer(raw["$ref"], openapi)
+            if resolved is None:
+                continue
+            raw = resolved
+        param = {k: raw[k] for k in _PARAM_KEYS if raw.get(k) is not None}
+        if isinstance(param.get("schema"), dict):
+            param["schema"] = flatten_schema(param["schema"], openapi, max_depth=max_depth)
+        parameters.append(param)
+
+    spec: dict[str, Any] = {
+        "method": method.upper(),
+        "path": path,
+        "summary": operation.get("summary"),
+        "description": operation.get("description"),
+        "parameters": parameters,
+    }
+    if operation.get("x-ai-hint"):
+        spec["businessHint"] = operation["x-ai-hint"]
+
+    request_body = operation.get("requestBody")
+    if isinstance(request_body, dict):
+        if isinstance(request_body.get("$ref"), str):
+            request_body = _resolve_pointer(request_body["$ref"], openapi) or {}
+        media_type, media = _pick_body_content(request_body)
+        if media is not None:
+            spec["requestBody"] = {
+                "contentType": media_type,
+                "required": bool(request_body.get("required")),
+                "schema": flatten_schema(media.get("schema") or {}, openapi, max_depth=max_depth),
+                "examples": media.get("examples") or media.get("example"),
+            }
+
+    return {k: v for k, v in spec.items() if v not in (None, [], {})}

fastapi_docs_plus/static/adapter.js

@@ -0,0 +1,197 @@
+/**
+ * Compatibility layer for Swagger UI internals.
+ *
+ * Swagger UI's internal actions and selectors are not a stable public API and
+ * may change between releases. Every call into them is confined to this file,
+ * so upgrading Swagger UI only requires adapting this module.
+ * Verified against: swagger-ui-dist 5.x
+ */
+(function () {
+  "use strict";
+
+  /**
+   * Find the raw (meta-free) parameter object for the given name and location.
+   *
+   * Swagger UI stores parameter values under keys of the form
+   * `${in}.${name}.hash-${param.hashCode()}`, where the hash is computed from
+   * the raw parameter object that ParameterRow reads. Objects returned by
+   * `operationWithMeta()` carry `value` / `errors` fields, produce a different
+   * hash, and writing through them lands on a key nobody reads, failing
+   * silently.
+   *
+   * @param {Object} system - Swagger UI system object.
+   * @param {string} path - Operation path, e.g. "/shops/{shop_id}".
+   * @param {string} method - Lowercase HTTP method, e.g. "get".
+   * @param {string} name - Parameter name.
+   * @param {string} location - One of "path", "query", "header", "cookie".
+   * @returns {Object|null} Raw parameter object, or null when not found.
+   */
+  function findRawParam(system, path, method, name, location) {
+    var selectors = system.specSelectors;
+    var specs = [];
+    try {
+      if (selectors.specJsonWithResolvedSubtrees) specs.push(selectors.specJsonWithResolvedSubtrees());
+      if (selectors.specJson) specs.push(selectors.specJson());
+    } catch (err) {
+      return null;
+    }
+    var containers = [
+      ["paths", path, method, "parameters"],
+      ["paths", path, "parameters"],
+    ];
+    for (var i = 0; i < specs.length; i++) {
+      for (var j = 0; j < containers.length; j++) {
+        var params = specs[i] && specs[i].getIn ? specs[i].getIn(containers[j]) : null;
+        if (!params || !params.find) continue;
+        var found = params.find(function (p) {
+          return p.get("name") === name && p.get("in") === location;
+        });
+        if (found) return found;
+      }
+    }
+    return null;
+  }
+
+  /**
+   * Convert a JSON value into the shape expected by Swagger UI field components.
+   *
+   * Array parameters are returned as arrays because the array input component
+   * expects the array itself; serializing them would render a single string item.
+   *
+   * @param {*} value - Raw JSON value.
+   * @returns {string|Array} Value ready to be written into the form field.
+   */
+  function toFieldValue(value) {
+    if (value === null || value === undefined) return "";
+    if (typeof value === "string") return value;
+    if (Array.isArray(value)) return value.map(toFieldValue);
+    if (typeof value === "object") return JSON.stringify(value);
+    return String(value);
+  }
+
+  /**
+   * Build an Error carrying a message code and its interpolation values.
+   *
+   * @param {string} code - Message code recognized by docs-plus.js.
+   * @param {string} message - Fallback English message.
+   * @param {Object} [values] - Values interpolated into the localized message.
+   * @returns {Error} Decorated error object.
+   */
+  function adapterError(code, message, values) {
+    var error = new Error(message);
+    error.code = code;
+    error.values = values;
+    return error;
+  }
+
+  window.DocsPlusAdapter = {
+    /**
+     * Expand the operation block so its RequestBody component gets mounted.
+     *
+     * While collapsed, the RequestBody component is not mounted yet and its
+     * automatically generated example overwrites the values we write on mount,
+     * so the block must be expanded before filling anything.
+     *
+     * @param {HTMLElement} button - AI button inside the operation summary.
+     * @returns {Promise<void>} Resolves once the block is expanded, or
+     *   immediately when it is already expanded.
+     */
+    ensureOperationExpanded: function (button) {
+      var block = button && button.closest ? button.closest(".opblock") : null;
+      if (!block || block.querySelector(".opblock-body")) return Promise.resolve();
+      var control = block.querySelector(".opblock-summary-control");
+      if (!control) return Promise.resolve();
+      control.click();
+      return new Promise(function (resolve) {
+        setTimeout(resolve, 350);
+      });
+    },
+
+    /**
+     * Write a value into a single parameter field.
+     *
+     * @param {Object} system - Swagger UI system object.
+     * @param {string} path - Operation path, e.g. "/shops/{shop_id}".
+     * @param {string} method - Lowercase HTTP method, e.g. "get".
+     * @param {string} name - Parameter name.
+     * @param {string} location - One of "path", "query", "header", "cookie".
+     * @param {*} value - Value to write.
+     * @returns {boolean} True on success.
+     * @throws {Error} With code "parameterNotFound" when the parameter is not
+     *   declared in the OpenAPI document, or "paramActionMissing" when the
+     *   Swagger UI version lacks the required action.
+     */
+    setParamValue: function (system, path, method, name, location, value) {
+      var param = findRawParam(system, path, method, name, location);
+      if (!param) {
+        throw adapterError("parameterNotFound", "Parameter not found in OpenAPI: " + location + "." + name, {
+          parameter: location + "." + name,
+        });
+      }
+      if (!system.specActions || !system.specActions.changeParamByIdentity) {
+        throw adapterError("paramActionMissing", "Swagger UI is missing the changeParamByIdentity action");
+      }
+      system.specActions.changeParamByIdentity([path, method], param, toFieldValue(value), false);
+      return true;
+    },
+
+    /**
+     * Write the request body into the body editor.
+     *
+     * @param {Object} system - Swagger UI system object.
+     * @param {string} path - Operation path, e.g. "/shops/{shop_id}".
+     * @param {string} method - Lowercase HTTP method, e.g. "post".
+     * @param {*} value - Body value; non-strings are pretty-printed as JSON.
+     * @returns {boolean} True on success.
+     * @throws {Error} With code "bodyActionMissing" when the Swagger UI
+     *   version lacks the required action.
+     */
+    setRequestBody: function (system, path, method, value) {
+      var text = typeof value === "string" ? value : JSON.stringify(value, null, 2);
+      if (system.oas3Actions && system.oas3Actions.setRequestBodyValue) {
+        system.oas3Actions.setRequestBodyValue({ value: text, pathMethod: [path, method] });
+        return true;
+      }
+      throw adapterError("bodyActionMissing", "Swagger UI is missing the setRequestBodyValue action");
+    },
+
+    /**
+     * Trigger parameter validation after filling.
+     *
+     * Validation is best-effort; a failure does not affect the filled values.
+     *
+     * @param {Object} system - Swagger UI system object.
+     * @param {string} path - Operation path, e.g. "/shops/{shop_id}".
+     * @param {string} method - Lowercase HTTP method, e.g. "get".
+     */
+    validateParams: function (system, path, method) {
+      try {
+        if (system.specActions && system.specActions.validateParams) {
+          system.specActions.validateParams([path, method], false);
+        }
+      } catch (err) {
+        /* Validation is best-effort; failures must not affect the filled values. */
+      }
+    },
+
+    /**
+     * Read the path and method from an OperationSummary component's props.
+     *
+     * @param {Object} props - Props of the OperationSummary component.
+     * @returns {{path: string, method: string}|null} Path and method, or null
+     *   when they cannot be determined.
+     */
+    readPathMethod: function (props) {
+      var operationProps = props && props.operationProps;
+      if (operationProps && typeof operationProps.get === "function") {
+        var path = operationProps.get("path");
+        var method = operationProps.get("method");
+        if (path && method) return { path: path, method: method };
+      }
+      if (props && props.path && props.method) {
+        return { path: props.path, method: props.method };
+      }
+      return null;
+    },
+  };
+})();

fastapi_docs_plus/static/docs-plus.css

@@ -0,0 +1,122 @@
+/* ------------------------------------------------------------------ Base */
+body {
+  margin: 0;
+  background: #fafafa;
+}
+
+/* -------------------------------------------------------------- Top bar */
+#docs-plus-bar {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: baseline;
+  gap: 12px;
+  padding: 10px 20px;
+  background: #1b1b1b;
+  color: #eee;
+  font: 13px/1.5 -apple-system, "Segoe UI", "Microsoft YaHei", sans-serif;
+}
+
+#docs-plus-bar label {
+  display: inline-flex;
+  align-items: center;
+  gap: 6px;
+  flex: 0 0 auto;
+}
+
+#docs-plus-bar select,
+#docs-plus-bar textarea {
+  font: inherit;
+  color: #eee;
+  background: #2c2c2c;
+  border: 1px solid #444;
+  border-radius: 4px;
+  padding: 4px 6px;
+}
+
+#docs-plus-bar select:focus-visible,
+#docs-plus-bar textarea:focus-visible,
+.docs-plus-ai-btn:focus-visible {
+  outline: 2px solid #9ecbff;
+  outline-offset: 2px;
+}
+
+#docs-plus-bar textarea {
+  box-sizing: border-box;
+  width: 100%;
+  min-height: 72px;
+  margin-top: 6px;
+  font-family: ui-monospace, Consolas, monospace;
+}
+
+#docs-plus-bar details {
+  flex: 1 1 auto;
+  min-width: 0;
+}
+
+#docs-plus-bar summary {
+  cursor: pointer;
+  color: #9ecbff;
+}
+
+#docs-plus-bar .docs-plus-note {
+  color: #f0b849;
+}
+
+/* ----------------------------------------------- Operation AI buttons */
+.docs-plus-op-summary {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+}
+
+.docs-plus-op-summary > *:first-child {
+  flex: 1 1 auto;
+  min-width: 0;
+}
+
+.docs-plus-ai-btn {
+  flex: 0 0 auto;
+  margin-right: 10px;
+  padding: 5px 12px;
+  font: 600 12px/1 -apple-system, "Segoe UI", "Microsoft YaHei", sans-serif;
+  color: #fff;
+  background: #4a5cf0;
+  border: 0;
+  border-radius: 4px;
+  cursor: pointer;
+}
+
+.docs-plus-ai-btn:disabled {
+  opacity: 0.6;
+  cursor: progress;
+}
+
+.docs-plus-fill-btn {
+  background: #2b7a3d;
+}
+
+.docs-plus-fill-btn.is-empty {
+  background: #5b6470;
+  opacity: 0.7;
+  cursor: not-allowed;
+}
+
+/* -------------------------------------------------------------- Toast */
+#docs-plus-toast {
+  position: fixed;
+  right: 20px;
+  bottom: 20px;
+  z-index: 9999;
+  max-width: 460px;
+  padding: 12px 16px;
+  color: #fff;
+  background: #2b7a3d;
+  border-radius: 6px;
+  box-shadow: 0 4px 16px rgba(0, 0, 0, 0.25);
+  font: 13px/1.5 -apple-system, "Segoe UI", "Microsoft YaHei", sans-serif;
+  white-space: pre-wrap;
+}
+
+#docs-plus-toast.is-error {
+  background: #b3323c;
+}