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

fastapi_docs_plus/__init__.py

@@ -0,0 +1,9 @@
+from .config import DocsPlusConfig
+from .docs_plus import setup_docs_plus
+from .pre_request import PreRequestContext
+
+__all__ = [
+    "DocsPlusConfig",
+    "PreRequestContext",
+    "setup_docs_plus",
+]

fastapi_docs_plus/ai_fill.py

@@ -0,0 +1,239 @@
+from __future__ import annotations
+
+import hashlib
+import json
+import re
+from collections import deque
+from dataclasses import dataclass, field
+from typing import Any
+
+from openai import AsyncOpenAI
+from jsonschema import Draft202012Validator
+
+from .config import DocsPlusConfig
+from .i18n import Language, language_instruction, translate
+
+_LOCATIONS = ("path", "query", "header", "cookie")
+_FENCE = re.compile(r"^\s*```(?:json)?\s*|\s*```\s*$")
+
+SYSTEM_PROMPT = """You generate realistic API request data from an OpenAPI operation specification.
+
+Output rules:
+1. Return one JSON object with only these keys: path, query, header, cookie, body.
+2. path/query/header/cookie map declared parameter names to scalar values; use {} for empty locations. Never invent parameters.
+3. body must strictly match requestBody.schema; use null when there is no requestBody.
+4. Obey enum, const, pattern, format, minimum/maximum, minLength/maxLength, minItems, required and all other schema constraints.
+5. Use description / examples / businessHint for business meaning, but write free-form natural-language values such as remark, comments, name, address and keyword in the selected output language, even when descriptions, examples or businessHint are Chinese or use another language.
+6. Never translate JSON keys, enum/const values, protocol identifiers, or fixed business codes/values. Language selection must not violate schema constraints, including country-specific phone formats.
+7. Use ISO 8601 timestamps, reasonable monetary amounts and realistic, correctly formatted IDs.
+8. Do not use placeholders such as "string", "foo", "test", 0 or empty strings unless the schema requires them. Include optional fields when useful.
+9. Do not output explanations, comments or Markdown fences.
+10. When generation history is provided, make new values clearly different from each previous result while obeying the schema and the selected output language. These language rules also apply to correction retries."""
+
+
+class AIFillError(RuntimeError):
+    """Raised when AI parameter generation fails for a known reason.
+
+    The error carries a localizable message key so callers can present
+    user-facing messages in the appropriate language.
+    """
+
+    def __init__(self, message_key: str, **params: Any) -> None:
+        self.message_key = message_key
+        self.params = params
+        super().__init__(self.localize())
+
+    def localize(self, language: Language = "en") -> str:
+        """Return the error message localized to *language*."""
+        params = {
+            key: value.localize(language) if isinstance(value, AIFillError) else value
+            for key, value in self.params.items()
+        }
+        return translate(self.message_key, language, **params)
+
+
+# ------------------------------------------------------------------ Cache
+
+@dataclass
+class _OpCache:
+    """Per-operation queue of cached generation results.
+
+    The cursor advances monotonically then wraps via modulo so that
+    evicting the oldest entry does not disturb the round-robin order.
+    """
+
+    schema_fingerprint: str
+    items: deque[dict] = field(default_factory=deque)
+    cursor: int = 0
+
+
+_CACHES: dict[tuple[Language, str], _OpCache] = {}
+
+
+def _op_key(path: str, method: str) -> str:
+    return f"{method.upper()} {path}"
+
+
+def _fingerprint(op_spec: dict) -> str:
+    return hashlib.sha256(json.dumps(op_spec, ensure_ascii=False, sort_keys=True).encode()).hexdigest()
+
+
+def next_fill(path: str, method: str, language: Language = "en") -> dict | None:
+    """Retrieve the next cached result for a given operation in round-robin order.
+
+    Returns ``None`` when the cache is empty.
+    """
+    entry = _CACHES.get((language, _op_key(path, method)))
+    if entry is None or not entry.items:
+        return None
+    index = entry.cursor % len(entry.items)
+    entry.cursor += 1
+    return {**entry.items[index], "cacheIndex": index, "cacheCount": len(entry.items)}
+
+
+def cache_counts(language: Language = "en") -> dict[str, int]:
+    """Return a mapping of ``"METHOD path"`` to cached-item count for *language*."""
+    return {
+        key: len(entry.items)
+        for (entry_language, key), entry in _CACHES.items()
+        if entry_language == language and entry.items
+    }
+
+
+# ------------------------------------------------------------------ Generation
+
+
+def _build_client(config: DocsPlusConfig):
+    if not config.llm_api_key:
+        raise AIFillError("missing_key")
+    return AsyncOpenAI(api_key=config.llm_api_key, base_url=config.llm_base_url)
+
+
+def _normalize(data: Any) -> dict:
+    if not isinstance(data, dict):
+        raise AIFillError("non_object")
+    result: dict[str, Any] = {}
+    for key in _LOCATIONS:
+        value = data.get(key)
+        result[key] = value if isinstance(value, dict) else {}
+    result["body"] = data.get("body")
+    return result
+
+
+def _prune(data: dict, op_spec: dict) -> dict:
+    """Remove parameters the model invented that are not declared in the schema."""
+    declared: dict[str, set[str]] = {location: set() for location in _LOCATIONS}
+    for param in op_spec.get("parameters", []):
+        location = param.get("in")
+        if location in declared and param.get("name"):
+            declared[location].add(param["name"])
+    for location in _LOCATIONS:
+        data[location] = {k: v for k, v in data[location].items() if k in declared[location]}
+    if not op_spec.get("requestBody"):
+        data["body"] = None
+    return data
+
+
+def _validate(data: dict, op_spec: dict) -> str | AIFillError | None:
+    body_schema = (op_spec.get("requestBody") or {}).get("schema")
+    if not body_schema:
+        return None
+    if data.get("body") is None:
+        return AIFillError("body_required") if op_spec["requestBody"].get("required") else None
+    errors = sorted(Draft202012Validator(body_schema).iter_errors(data["body"]), key=lambda e: list(e.path))
+    if not errors:
+        return None
+    return "; ".join(f"{'/'.join(map(str, e.path)) or '<root>'}: {e.message}" for e in errors[:5])
+
+
+async def _complete(client, config: DocsPlusConfig, messages: list[dict], temperature: float) -> dict:
+    response = await client.chat.completions.create(
+        model=config.llm_model,
+        messages=messages,
+        temperature=temperature,
+        response_format={"type": "json_object"},
+        timeout=config.llm_timeout,
+    )
+    if not response.choices:
+        raise AIFillError("empty_response")
+    raw = (response.choices[0].message.content or "").strip()
+    if not raw:
+        raise AIFillError("empty_response")
+    try:
+        return _normalize(json.loads(_FENCE.sub("", raw)))
+    except json.JSONDecodeError as exc:
+        raise AIFillError("invalid_json") from exc
+
+
+async def generate_and_cache(
+    op_spec: dict, config: DocsPlusConfig, *, path: str, method: str, language: Language = "en"
+) -> int:
+    """Generate parameter values via LLM and cache them on validation success.
+
+    Only results that pass ``jsonschema`` validation against the
+    operation's ``requestBody`` are added to the in-memory cache.
+    Returns the current number of cached items for this operation.
+
+    Args:
+        op_spec: Self-contained operation spec from
+            :func:`build_operation_spec`.
+        config: Global ``DocsPlusConfig``.
+        path: URL path for cache keying.
+        method: HTTP method for cache keying.
+        language: Output language for generated values.
+
+    Returns:
+        Number of cached items after insertion.
+
+    Raises:
+        AIFillError: On configuration issues, schema size overflow,
+            empty LLM responses, or repeated validation failure.
+    """
+    key = (language, _op_key(path, method))
+    fingerprint = _fingerprint(op_spec)
+    entry = _CACHES.get(key)
+    if entry is None or entry.schema_fingerprint != fingerprint:
+        # Schema changed — discard old cache (including history used as context)
+        entry = _OpCache(schema_fingerprint=fingerprint)
+        _CACHES[key] = entry
+
+    payload = json.dumps(op_spec, ensure_ascii=False, sort_keys=True)
+    history = list(entry.items)
+    if history:
+        compact = json.dumps(history, ensure_ascii=False, separators=(",", ":"))
+        payload += f"\n\nGeneration history (make new values clearly different):\n{compact}"
+    if len(payload) > config.max_schema_chars:
+        raise AIFillError("schema_too_large", size=len(payload), limit=config.max_schema_chars)
+
+    # More history → more diversity needed
+    temperature = min(1.0, config.llm_temperature + 0.1 * min(len(history), 5))
+    instruction = language_instruction(language)
+    messages: list[dict] = [
+        {"role": "system", "content": f"{SYSTEM_PROMPT}\n\n{instruction}"},
+        {"role": "user", "content": payload},
+    ]
+
+    client = _build_client(config)
+    data = _prune(await _complete(client, config, messages, temperature), op_spec)
+
+    problem = _validate(data, op_spec)
+    if problem:
+        messages = [
+            *messages,
+            {"role": "assistant", "content": json.dumps(data, ensure_ascii=False)},
+            {
+                "role": "user",
+                "content": f"The previous output failed schema validation: {problem}\n"
+                f"Correct it and return the complete JSON object. {instruction}",
+            },
+        ]
+        retried = _prune(await _complete(client, config, messages, temperature), op_spec)
+        second_problem = _validate(retried, op_spec)
+        if second_problem:
+            raise AIFillError("validation_failed", problem=second_problem)
+        data = retried
+
+    entry.items.append(data)
+    while len(entry.items) > max(1, config.ai_cache_max_size):
+        entry.items.popleft()
+    return len(entry.items)

fastapi_docs_plus/config.py

@@ -0,0 +1,123 @@
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass, field
+
+
+def _env(*names: str, default: str | None = None) -> str | None:
+    """Read the first non-empty environment variable from *names."""
+    for name in names:
+        value = os.getenv(name)
+        if value:
+            return value
+    return default
+
+
+_DEFAULT_SWAGGER_UI_PARAMETERS: dict = {
+    "persistAuthorization": True,
+    "displayRequestDuration": True,
+    "docExpansion": "list",
+    "showExtensions": True,
+    "showCommonExtensions": True,
+}
+
+
+@dataclass
+class DocsPlusConfig:
+    """Configuration for fastapi-docs-plus.
+
+    Controls Swagger UI rendering, AI parameter generation, and
+    pre-request hook behaviour.
+
+    Attributes:
+        docs_url: Path for the documentation page (default ``"/docs"``).
+        api_prefix: Prefix for internal API endpoints and static assets
+            (default ``"/_docs"``).
+        openapi_url: URL where Swagger UI fetches the OpenAPI spec
+            (default ``"/openapi.json"``).
+        swagger_ui_version: Swagger UI version used to build CDN URLs
+            (default ``"5.17.14"``).
+        swagger_ui_js_url: Override for the Swagger UI JS bundle URL.
+            When ``None`` the CDN URL is used.
+        swagger_ui_css_url: Override for the Swagger UI CSS URL.
+            When ``None`` the CDN URL is used.
+        swagger_ui_js_integrity: Subresource Integrity hash for the JS
+            bundle. When set, an ``integrity`` attribute is emitted.
+        swagger_ui_css_integrity: Subresource Integrity hash for the
+            CSS. When set, an ``integrity`` attribute is emitted.
+        swagger_ui_parameters: Extra parameters passed to the
+            ``SwaggerUIBundle`` constructor. Merged key-wise over the
+            defaults, so only the keys you provide are overridden and
+            the rest keep their default values. Defaults enable
+            ``persistAuthorization``, ``displayRequestDuration``,
+            ``docExpansion="list"``, ``showExtensions`` and
+            ``showCommonExtensions``.
+        identities: List of identity labels shown in the top-bar
+            dropdown. An empty list hides the dropdown entirely.
+        llm_model: LLM model identifier (default ``"gpt-4o-mini"``).
+        llm_base_url: Base URL for the OpenAI-compatible API. Reads
+            ``DOCS_PLUS_LLM_BASE_URL`` or ``OPENAI_BASE_URL``.
+        llm_api_key: API key for the LLM service. Reads
+            ``DOCS_PLUS_LLM_API_KEY`` or ``OPENAI_API_KEY``.
+        llm_temperature: Temperature for LLM calls. Automatically
+            increased by ``0.1`` per cached history entry, capped at
+            ``1.0`` (default ``0.3``).
+        llm_timeout: Timeout in seconds for each LLM call
+            (default ``60.0``).
+        max_schema_depth: Maximum depth for inlining ``$ref`` schemas
+            (default ``4``).
+        max_schema_chars: Maximum total characters for the schema plus
+            cached history. Beyond this the request is rejected without
+            calling the LLM (default ``60_000``).
+        ai_cache_max_size: Maximum number of validated AI-generated
+            results kept per operation in the in-memory cache. Oldest
+            entries are evicted first (default ``5``).
+    """
+
+    docs_url: str = "/docs"
+    api_prefix: str = "/_docs"
+    openapi_url: str = "/openapi.json"
+
+    swagger_ui_version: str = "5.17.14"
+    swagger_ui_js_url: str | None = None
+    swagger_ui_css_url: str | None = None
+    swagger_ui_js_integrity: str | None = None
+    swagger_ui_css_integrity: str | None = None
+    swagger_ui_parameters: dict = field(default_factory=dict)
+
+    identities: list[str] = field(default_factory=list)
+
+    llm_model: str = field(default_factory=lambda: _env("DOCS_PLUS_LLM_MODEL", default="gpt-4o-mini"))
+    llm_base_url: str | None = field(default_factory=lambda: _env("DOCS_PLUS_LLM_BASE_URL", "OPENAI_BASE_URL"))
+    llm_api_key: str | None = field(default_factory=lambda: _env("DOCS_PLUS_LLM_API_KEY", "OPENAI_API_KEY"))
+    llm_temperature: float = 0.3
+    llm_timeout: float = 60.0
+
+    max_schema_depth: int = 4
+    max_schema_chars: int = 60_000
+
+    ai_cache_max_size: int = 5
+
+    def __post_init__(self) -> None:
+        self.swagger_ui_parameters = {
+            **_DEFAULT_SWAGGER_UI_PARAMETERS,
+            **(self.swagger_ui_parameters or {}),
+        }
+
+    @property
+    def ai_enabled(self) -> bool:
+        return bool(self.llm_api_key)
+
+    @property
+    def static_url(self) -> str:
+        return f"{self.api_prefix}/static"
+
+    @property
+    def resolved_js_url(self) -> str:
+        base = f"https://cdn.jsdelivr.net/npm/swagger-ui-dist@{self.swagger_ui_version}"
+        return self.swagger_ui_js_url or f"{base}/swagger-ui-bundle.js"
+
+    @property
+    def resolved_css_url(self) -> str:
+        base = f"https://cdn.jsdelivr.net/npm/swagger-ui-dist@{self.swagger_ui_version}"
+        return self.swagger_ui_css_url or f"{base}/swagger-ui.css"

fastapi_docs_plus/docs_plus.py

@@ -0,0 +1,171 @@
+from __future__ import annotations
+
+import json
+from html import escape
+from pathlib import Path
+from typing import Any
+
+from fastapi import FastAPI, HTTPException
+from fastapi.responses import HTMLResponse
+from fastapi.staticfiles import StaticFiles
+from openai import OpenAIError
+from pydantic import BaseModel, Field
+
+from .ai_fill import AIFillError, cache_counts, generate_and_cache, next_fill
+from .config import DocsPlusConfig
+from .i18n import Language, translate
+from .pre_request import PreRequestHook, build_context, run_hooks
+from .schema_utils import build_operation_spec
+
+STATIC_DIR = Path(__file__).parent / "static"
+
+
+def _asset_tag(kind: str, url: str, integrity: str | None) -> str:
+    attrs = f'integrity="{escape(integrity, quote=True)}" crossorigin="anonymous" ' if integrity else ""
+    if kind == "css":
+        return f'<link rel="stylesheet" {attrs}href="{escape(url, quote=True)}" />'
+    return f'<script {attrs}src="{escape(url, quote=True)}"></script>'
+
+
+class _OpTarget(BaseModel):
+    path: str
+    method: str
+    language: Language = "en"
+
+
+class _PreRequestPayload(BaseModel):
+    method: str
+    url: str
+    headers: dict[str, str] = Field(default_factory=dict)
+    env: dict[str, Any] = Field(default_factory=dict)
+
+
+class DocsPlus:
+    """Enhanced interactive API docs with AI parameter filling and Python-side pre-request hooks.
+
+    Usage::
+
+        docs = DocsPlus(app, DocsPlusConfig(...))
+
+        @docs.pre_request
+        async def inject_auth(ctx: PreRequestContext) -> None:
+            ctx.headers["Authorization"] = f"Bearer {token}"
+    """
+
+    def __init__(self, app: FastAPI, config: DocsPlusConfig | None = None) -> None:
+        self.app = app
+        self.config = config or DocsPlusConfig()
+        self._hooks: list[PreRequestHook] = []
+        self._register_routes()
+
+    def pre_request(self, hook: PreRequestHook) -> PreRequestHook:
+        """Register a pre-request hook.
+
+        Multiple hooks execute in registration order and share the same
+        :class:`PreRequestContext`.
+
+        Args:
+            hook: A synchronous or asynchronous callable that receives a
+                :class:`PreRequestContext`.
+
+        Returns:
+            The same callable (allows use as a decorator).
+        """
+        self._hooks.append(hook)
+        return hook
+
+    def _register_routes(self) -> None:
+        app, config = self.app, self.config
+        app.mount(config.static_url, StaticFiles(directory=STATIC_DIR), name="docs_plus_static")
+
+        @app.get(config.docs_url, include_in_schema=False)
+        async def docs_page() -> HTMLResponse:
+            return HTMLResponse(self._render_page())
+
+        @app.post(f"{config.api_prefix}/api/ai/generate", include_in_schema=False)
+        async def ai_generate(payload: _OpTarget) -> dict:
+            try:
+                op_spec = build_operation_spec(
+                    app.openapi(), payload.path, payload.method, max_depth=config.max_schema_depth
+                )
+            except KeyError as exc:
+                raise HTTPException(
+                    status_code=404,
+                    detail=translate(
+                        "operation_not_found", payload.language,
+                        method=payload.method.upper(), path=payload.path,
+                    ),
+                ) from exc
+            try:
+                count = await generate_and_cache(
+                    op_spec, config, path=payload.path, method=payload.method,
+                    language=payload.language,
+                )
+            except AIFillError as exc:
+                raise HTTPException(status_code=503, detail=exc.localize(payload.language)) from exc
+            except OpenAIError as exc:
+                raise HTTPException(
+                    status_code=503, detail=translate("service_error", payload.language)
+                ) from exc
+            return {"count": count}
+
+        @app.post(f"{config.api_prefix}/api/ai/fill", include_in_schema=False)
+        async def ai_fill(payload: _OpTarget) -> dict:
+            result = next_fill(payload.path, payload.method, payload.language)
+            if result is None:
+                raise HTTPException(status_code=409, detail=translate("empty_cache", payload.language))
+            return result
+
+        @app.get(f"{config.api_prefix}/api/ai/cache", include_in_schema=False)
+        async def ai_cache(language: Language = "en") -> dict:
+            return {"counts": cache_counts(language)}
+
+        @app.post(f"{config.api_prefix}/api/pre-request", include_in_schema=False)
+        async def pre_request(payload: _PreRequestPayload) -> dict:
+            ctx = build_context(
+                app,
+                method=payload.method,
+                url=payload.url,
+                headers=payload.headers,
+                env=payload.env,
+            )
+            await run_hooks(self._hooks, ctx)
+            return {
+                "headers": {k: str(v) for k, v in ctx.headers.items() if v is not None},
+                "query": {k: str(v) for k, v in ctx.query.items() if v is not None},
+                "operationId": ctx.operation_id,
+            }
+
+    def _render_page(self) -> str:
+        config = self.config
+        front_config = {
+            "openapiUrl": config.openapi_url,
+            "apiPrefix": config.api_prefix,
+            "identities": config.identities,
+            "aiEnabled": config.ai_enabled,
+            "hasPreRequestHook": bool(self._hooks),
+            "swaggerUiParameters": config.swagger_ui_parameters,
+        }
+        template = (STATIC_DIR / "docs.html").read_text(encoding="utf-8")
+        return (
+            template.replace("__STATIC_URL__", escape(config.static_url, quote=True))
+            .replace("__SWAGGER_CSS_TAG__", _asset_tag("css", config.resolved_css_url, config.swagger_ui_css_integrity))
+            .replace("__SWAGGER_JS_TAG__", _asset_tag("js", config.resolved_js_url, config.swagger_ui_js_integrity))
+            .replace("__CONFIG__", json.dumps(front_config, ensure_ascii=False).replace("</", "<\\/"))
+        )
+
+
+def setup_docs_plus(app: FastAPI, config: DocsPlusConfig | None = None) -> DocsPlus:
+    """Create and register a :class:`DocsPlus` instance on the given FastAPI application.
+
+    This is a convenience wrapper around ``DocsPlus(app, config)``.
+
+    Args:
+        app: The FastAPI application instance.
+        config: Optional configuration. Falls back to defaults.
+
+    Returns:
+        The :class:`DocsPlus` instance (use it to register hooks via
+        :meth:`DocsPlus.pre_request`).
+    """
+    return DocsPlus(app, config)

fastapi_docs_plus/i18n.py

@@ -0,0 +1,61 @@
+from __future__ import annotations
+
+from typing import Any, Literal
+
+Language = Literal["en", "zh"]
+
+_MESSAGES: dict[Language, dict[str, str]] = {
+    "en": {
+        "missing_key": "LLM credentials are not configured. Set DOCS_PLUS_LLM_API_KEY or OPENAI_API_KEY.",
+        "empty_response": "The model returned empty content.",
+        "invalid_json": "The model returned invalid JSON.",
+        "non_object": "The model did not return a JSON object.",
+        "schema_too_large": "The operation schema and history are too large ({size} characters); the limit is {limit}.",
+        "validation_failed": "Both attempts failed schema validation; nothing was cached: {problem}",
+        "body_required": "requestBody is required, but body is null.",
+        "empty_cache": "No AI-generated data is cached for this operation. Click AI Generate first.",
+        "operation_not_found": "Operation not found in OpenAPI: {method} {path}",
+        "service_error": "The AI service is unavailable. Please check the service configuration or try again later.",
+    },
+    "zh": {
+        "missing_key": "未配置 LLM 凭据，请设置环境变量 DOCS_PLUS_LLM_API_KEY 或 OPENAI_API_KEY。",
+        "empty_response": "模型返回了空内容。",
+        "invalid_json": "模型返回的内容不是合法 JSON。",
+        "non_object": "模型返回的不是 JSON 对象。",
+        "schema_too_large": "该接口的 schema 和历史过大（{size} 字符），已超出上限 {limit}。",
+        "validation_failed": "两次生成均未通过 schema 校验，未缓存：{problem}",
+        "body_required": "requestBody 是必填的，但 body 为 null。",
+        "empty_cache": "该接口暂无 AI 生成缓存，请先点击「AI 生成」。",
+        "operation_not_found": "OpenAPI 中不存在操作：{method} {path}",
+        "service_error": "AI 服务暂不可用，请检查服务配置或稍后重试。",
+    },
+}
+
+
+def translate(message_key: str, language: Language = "en", **params: Any) -> str:
+    """Look up a localized message and format it with the given parameters.
+
+    Args:
+        message_key: Key into the message dictionary.
+        language: Target language (``"en"`` or ``"zh"``).
+        **params: Format-string parameters injected via ``str.format``.
+
+    Returns:
+        The formatted localized string.
+    """
+    return _MESSAGES[language][message_key].format(**params)
+
+
+def language_instruction(language: Language = "en") -> str:
+    """Return a system-level language instruction for the LLM prompt.
+
+    Args:
+        language: Target language (``"en"`` or ``"zh"``).
+
+    Returns:
+        A short instruction string such as ``"Output language: English."``.
+    """
+    return {
+        "en": "Output language: English.",
+        "zh": "Output language: Simplified Chinese.",
+    }[language]