drf-to-mkdoc 0.1.9__py3-none-any.whl → 0.2.1__py3-none-any.whl

drf_to_mkdoc/utils/commons/schema_utils.py

@@ -0,0 +1,230 @@
+import json
+from pathlib import Path
+from typing import Any
+
+import yaml
+from drf_spectacular.generators import SchemaGenerator
+
+from drf_to_mkdoc.conf.settings import drf_to_mkdoc_settings
+from drf_to_mkdoc.utils.commons.file_utils import load_json_data
+
+
+class SchemaValidationError(Exception):
+    """Custom exception for schema validation errors."""
+
+    pass
+
+
+class QueryParamTypeError(Exception):
+    """Custom exception for query parameter type errors."""
+
+    pass
+
+
+def load_schema() -> dict[str, Any] | None:
+    """Load the OpenAPI schema from doc-schema.yaml"""
+    schema_file = Path(drf_to_mkdoc_settings.CONFIG_DIR) / "doc-schema.yaml"
+    if not schema_file.exists():
+        return None
+
+    with schema_file.open(encoding="utf-8") as f:
+        return yaml.safe_load(f)
+
+
+def get_custom_schema():
+    custom_schema_data = load_json_data(
+        drf_to_mkdoc_settings.CUSTOM_SCHEMA_FILE, raise_not_found=False
+    )
+    if not custom_schema_data:
+        return {}
+
+    for _operation_id, overrides in custom_schema_data.items():
+        parameters = overrides.get("parameters", [])
+        if not parameters:
+            continue
+        for parameter in parameters:
+            if {"name", "in", "description", "required", "schema"} - set(parameter.keys()):
+                raise SchemaValidationError("Required keys are not passed")
+
+            if parameter["in"] == "query":
+                queryparam_type = parameter.get("queryparam_type")
+                if not queryparam_type:
+                    raise QueryParamTypeError("queryparam_type is required for query")
+
+                if queryparam_type not in (
+                    {
+                        "search_fields",
+                        "filter_fields",
+                        "ordering_fields",
+                        "filter_backends",
+                        "pagination_fields",
+                    }
+                ):
+                    raise QueryParamTypeError("Invalid queryparam_type")
+
+    return custom_schema_data
+
+
+def _merge_parameters(
+    base_parameters: list[dict[str, Any]], custom_parameters: list[dict[str, Any]]
+) -> list[dict[str, Any]]:
+    """
+    Merge parameters from base and custom schemas, avoiding duplicates.
+
+    Parameters are considered duplicates if they have the same 'name' and 'in' values.
+    Custom parameters will override base parameters with the same (name, in) key.
+    """
+
+    def _get_param_key(param: dict[str, Any]) -> tuple[str, str] | None:
+        """Extract (name, in) tuple from parameter, return None if invalid."""
+        name = param.get("name")
+        location = param.get("in")
+        return (name, location) if name and location else None
+
+    param_index = {}
+    for param in base_parameters:
+        key = _get_param_key(param)
+        if key:
+            param_index[key] = param
+
+    for param in custom_parameters:
+        key = _get_param_key(param)
+        if key:
+            param_index[key] = param
+
+    return list(param_index.values())
+
+
+def _build_operation_map(base_schema: dict) -> dict[str, tuple[str, str]]:
+    """Build a mapping from operationId → (path, method)."""
+    op_map = {}
+    HTTP_METHODS = {"get", "post", "put", "patch", "delete", "options", "head", "trace"}
+
+    for path, actions in base_schema.get("paths", {}).items():
+        for method, op_data in actions.items():
+            if method.lower() not in HTTP_METHODS or not isinstance(op_data, dict):
+                continue
+            if not op_data.get("x-metadata"):
+                raise ValueError(
+                    "Missing x-metadata in OpenAPI schema. Please ensure you're using the custom AutoSchema in your REST_FRAMEWORK settings:\n"
+                    "REST_FRAMEWORK = {\n"
+                    "    'DEFAULT_SCHEMA_CLASS': 'drf_to_mkdoc.utils.schema.AutoSchema',\n"
+                    "}\n"
+                )
+            operation_id = op_data.get("operationId")
+            if operation_id:
+                op_map[operation_id] = (path, method)
+
+    return op_map
+
+
+def _apply_custom_overrides(
+    base_schema: dict,
+    op_map: dict[str, tuple[str, str]],
+    custom_data: dict,
+) -> None:
+    """Apply custom overrides to the base schema."""
+    allowed_keys = {"description", "parameters", "requestBody", "responses"}
+
+    for operation_id, overrides in custom_data.items():
+        if operation_id not in op_map:
+            continue
+
+        append_fields = set(overrides.get("append_fields", []))
+        path, method = op_map[operation_id]
+        target_schema = base_schema["paths"][path][method]
+
+        for key in allowed_keys:
+            if key not in overrides:
+                continue
+
+            custom_value = overrides[key]
+            base_value = target_schema.get(key)
+
+            if key in append_fields:
+                if isinstance(base_value, list) and isinstance(custom_value, list):
+                    if key == "parameters":
+                        target_schema[key] = _merge_parameters(base_value, custom_value)
+                    else:
+                        target_schema[key].extend(custom_value)
+                else:
+                    target_schema[key] = custom_value
+            else:
+                target_schema[key] = custom_value
+
+
+def get_schema():
+    base_schema = SchemaGenerator().get_schema(request=None, public=True)
+    custom_data = get_custom_schema()
+    if not custom_data:
+        return base_schema
+
+    operation_map = _build_operation_map(base_schema)
+    _apply_custom_overrides(base_schema, operation_map, custom_data)
+
+    return base_schema
+
+
+class OperationExtractor:
+    """Extracts operation IDs and metadata from OpenAPI schema."""
+
+    _instance = None
+
+    def __new__(cls):
+        if cls._instance is None:
+            cls._instance = super().__new__(cls)
+            cls._instance._initialized = False
+        return cls._instance
+
+    def __init__(self):
+        if not self._initialized:
+            self.schema = get_schema()
+            self._operation_map = None
+            self._initialized = True
+
+    def save_operation_map(self) -> None:
+        """Save operation map to file."""
+        if not self._operation_map:
+            self._operation_map = self._build_operation_map()
+
+        operation_map_path = Path(drf_to_mkdoc_settings.AI_OPERATION_MAP_FILE)
+        # Create parent directories if they don't exist
+        operation_map_path.parent.mkdir(parents=True, exist_ok=True)
+
+        with operation_map_path.open("w", encoding="utf-8") as f:
+            json.dump(self._operation_map, f, indent=2)
+
+    @property
+    def operation_map(self) -> dict[str, dict[str, Any]] | None:
+        """
+        Cache and return operation ID mapping.
+         Returns dict: operation_id -> {"path": str, ...metadata}
+        """
+        if self._operation_map is None:
+            # Try to load from file first
+            self._operation_map = load_json_data(
+                drf_to_mkdoc_settings.AI_OPERATION_MAP_FILE, raise_not_found=False
+            )
+
+            # If not found or invalid, build and save
+            if self._operation_map is None:
+                self._operation_map = self._build_operation_map()
+                self.save_operation_map()
+
+        return self._operation_map
+
+    def _build_operation_map(self) -> dict[str, dict[str, Any]] | None:
+        """Build mapping of operation IDs to paths and metadata."""
+        mapping = {}
+        paths = self.schema.get("paths", {})
+
+        for path, methods in paths.items():
+            for _method, operation in methods.items():
+                operation_id = operation.get("operationId")
+                if not operation_id:
+                    continue
+
+                metadata = operation.get("x-metadata", {})
+                mapping[operation_id] = {"path": path, **metadata}
+
+        return mapping

drf_to_mkdoc/utils/endpoint_detail_generator.py

@@ -10,14 +10,14 @@ from django.templatetags.static import static
 from rest_framework import serializers
 
 from drf_to_mkdoc.conf.settings import drf_to_mkdoc_settings
-from drf_to_mkdoc.utils.common import (
-    create_safe_filename,
+from drf_to_mkdoc.utils.commons.file_utils import write_file
+from drf_to_mkdoc.utils.commons.operation_utils import (
     extract_app_from_operation_id,
     extract_viewset_name_from_operation_id,
     format_method_badge,
-    get_custom_schema,
-    write_file,
 )
+from drf_to_mkdoc.utils.commons.path_utils import create_safe_filename
+from drf_to_mkdoc.utils.commons.schema_utils import get_custom_schema
 from drf_to_mkdoc.utils.extractors.query_parameter_extractors import (
     extract_query_parameters_from_view,
 )
@@ -32,17 +32,17 @@ def analyze_serializer_method_field_schema(serializer_class, field_name: str) ->
     """Analyze a SerializerMethodField to determine its actual return type schema."""
     method_name = f"get_{field_name}"
 
-    # Strategy 2: Check type annotations
+    # Strategy 1: Check type annotations
     schema_from_annotations = _extract_schema_from_type_hints(serializer_class, method_name)
     if schema_from_annotations:
         return schema_from_annotations
 
-    # Strategy 3: Analyze method source code
+    # Strategy 2: Analyze method source code
     schema_from_source = _analyze_method_source_code(serializer_class, method_name)
     if schema_from_source:
         return schema_from_source
 
-    # Strategy 4: Runtime analysis (sample execution)
+    # Strategy 3: Runtime analysis (sample execution)
     schema_from_runtime = _analyze_method_runtime(serializer_class, method_name)
     if schema_from_runtime:
         return schema_from_runtime
@@ -51,33 +51,6 @@ def analyze_serializer_method_field_schema(serializer_class, field_name: str) ->
     return {"type": "string"}
 
 
-def _extract_schema_from_decorator(serializer_class, method_name: str) -> dict:
-    """Extract schema from @extend_schema_field decorator if present."""
-    try:
-        method = getattr(serializer_class, method_name, None)
-        if not method:
-            return {}
-
-        # Check if method has the decorator attribute (drf-spectacular)
-        if hasattr(method, "_spectacular_annotation"):
-            annotation = method._spectacular_annotation
-            # Handle OpenApiTypes
-            if hasattr(annotation, "type"):
-                return {"type": annotation.type}
-            if isinstance(annotation, dict):
-                return annotation
-
-        # Check for drf-yasg decorator
-        if hasattr(method, "_swagger_serializer_method"):
-            swagger_info = method._swagger_serializer_method
-            if hasattr(swagger_info, "many") and hasattr(swagger_info, "child"):
-                return {"type": "array", "items": {"type": "object"}}
-
-    except Exception:
-        logger.exception("Failed to extract schema from decorator")
-    return {}
-
-
 def _extract_schema_from_type_hints(serializer_class, method_name: str) -> dict:
     """Extract schema from method type annotations."""
     try:
@@ -572,14 +545,22 @@ def _create_endpoint_header(
         "stylesheets/endpoints/animations.css",
         "stylesheets/endpoints/accessibility.css",
         "stylesheets/endpoints/loading.css",
+        "stylesheets/endpoints/try-out-sidebar.css",
+    ]
+    scripts = [
+        "javascripts/try-out-sidebar.js",
     ]
     prefix_path = f"{drf_to_mkdoc_settings.PROJECT_NAME}/"
     css_links = "\n".join(
         f'<link rel="stylesheet" href="{static(prefix_path + path)}">' for path in stylesheets
     )
+    js_scripts = "\n".join(
+        f'<script src="{static(prefix_path + path)}" defer></script>' for path in scripts
+    )
     content = f"""
-<!-- inject CSS directly -->
+<!-- inject CSS and JS directly -->
 {css_links}
+{js_scripts}
 """
     content += f"# {method.upper()} {path}\n\n"
     content += f"{format_method_badge(method)} `{path}`\n\n"

drf_to_mkdoc/utils/endpoint_list_generator.py

@@ -4,7 +4,7 @@ from typing import Any
 from django.templatetags.static import static
 
 from drf_to_mkdoc.conf.settings import drf_to_mkdoc_settings
-from drf_to_mkdoc.utils.common import extract_viewset_from_operation_id
+from drf_to_mkdoc.utils.commons.operation_utils import extract_viewset_from_operation_id
 
 
 class EndpointsIndexGenerator:

drf_to_mkdoc/utils/extractors/query_parameter_extractors.py

@@ -1,8 +1,6 @@
 from typing import Any
 
-import django_filters
-
-from drf_to_mkdoc.utils.common import extract_viewset_from_operation_id
+from drf_to_mkdoc.utils.commons.operation_utils import extract_viewset_from_operation_id
 
 
 def extract_query_parameters_from_view(operation_id: str) -> dict[str, Any]:
@@ -111,35 +109,34 @@ def extract_query_parameters_from_view_pagination_fields(view_class: Any) -> lis
 
 
 def _extract_filterset_fields_from_class_attributes(filterset_class: Any) -> list[str]:
-    fields = []
-
     try:
-        # Get all class attributes, including inherited ones
-        for attr_name in dir(filterset_class):
-            # Skip private attributes and known non-filter attributes
-            if attr_name.startswith("_") or attr_name in [
-                "Meta",
-                "form",
-                "queryset",
-                "request",
-                "errors",
-                "qs",
-                "is_valid",
-            ]:
-                continue
-
-            try:
-                attr = getattr(filterset_class, attr_name)
-                if isinstance(attr, django_filters.Filter):
-                    if attr_name not in fields:
-                        fields.append(attr_name)
-            except (AttributeError, TypeError):
-                continue
-
+        import django_filters  # noqa: PLC0415
     except ImportError:
         # django_filters not available, skip this strategy
-        pass
+        return []
 
+    fields = []
+    # Get all class attributes, including inherited ones
+    for attr_name in dir(filterset_class):
+        # Skip private attributes and known non-filter attributes
+        if attr_name.startswith("_") or attr_name in [
+            "Meta",
+            "form",
+            "queryset",
+            "request",
+            "errors",
+            "qs",
+            "is_valid",
+        ]:
+            continue
+
+        try:
+            attr = getattr(filterset_class, attr_name)
+            if isinstance(attr, django_filters.Filter):
+                if attr_name not in fields:
+                    fields.append(attr_name)
+        except (AttributeError, TypeError):
+            continue
     return fields
 
 
@@ -182,7 +179,8 @@ def _extract_filterset_fields_from_internal_attrs(filterset_class: Any) -> list[
 
 
 def _extract_filterset_fields_from_get_fields(filterset_class: Any) -> list[str]:
-    if not (filterset_class._meta and filterset_class._meta.model):
+    meta = getattr(filterset_class, "_meta", None)
+    if not getattr(meta, "model", None):
         # If the Meta class is not defined in the Filter class,
         # the get_fields function is raise error
         return []
@@ -191,7 +189,12 @@ def _extract_filterset_fields_from_get_fields(filterset_class: Any) -> list[str]
     if not hasattr(filterset_class, "get_fields"):
         return []
 
-    filterset_instance = filterset_class()
+    try:
+        filterset_instance = filterset_class()
+    except TypeError:
+        # Constructor requires args; skip dynamic field discovery
+        return []
+
     filterset_fields = filterset_instance.get_fields()
     if not (filterset_fields and hasattr(filterset_fields, "keys")):
         return []

drf_to_mkdoc/utils/model_detail_generator.py

@@ -3,24 +3,31 @@ from typing import Any
 from django.templatetags.static import static
 
 from drf_to_mkdoc.conf.settings import drf_to_mkdoc_settings
-from drf_to_mkdoc.utils.common import get_model_description, write_file
+from drf_to_mkdoc.utils.commons.file_utils import write_file
+from drf_to_mkdoc.utils.commons.model_utils import get_model_description
 
 
 def generate_model_docs(models_data: dict[str, Any]) -> None:
     """Generate model documentation from JSON data"""
-    for model_name, model_info in models_data.items():
-        app_name = model_info.get("app_label", model_name.split(".")[0])
-        class_name = model_info.get("name", model_name.split(".")[-1])
+    for app_name, models in models_data.items():
+        if not isinstance(models, dict):
+            raise TypeError(f"Expected dict for models in app '{app_name}', got {type(models)}")
 
-        # Create the model page content
-        content = create_model_page(model_info)
+        for model_name, model_info in models.items():
+            if not isinstance(model_info, dict) or "name" not in model_info:
+                raise ValueError(
+                    f"Model info for '{model_name}' in app '{app_name}' is invalid"
+                )
 
-        # Write the file in app subdirectory
-        file_path = f"models/{app_name}/{class_name.lower()}.md"
-        write_file(file_path, content)
+            # Create the model page content
+            content = create_model_page(model_info)
 
+            # Write the file in app subdirectory
+            file_path = f"models/{app_name}/{model_info['table_name']}.md"
+            write_file(file_path, content)
 
-def render_fields_table(fields: dict[str, Any]) -> str:
+
+def render_column_fields_table(fields: dict[str, Any]) -> str:
     """Render the fields table for a model."""
     content = "## Fields\n\n"
     content += "| Field | Type | Description | Extra |\n"
@@ -31,6 +38,10 @@ def render_fields_table(fields: dict[str, Any]) -> str:
         verbose_name = field_info.get("verbose_name", field_name)
         help_text = field_info.get("help_text", "")
 
+        display_name = field_name
+        if field_type in ["ForeignKey", "OneToOneField"]:
+            display_name = f"{field_name}_id"
+
         extra_info = []
         if field_info.get("null"):
             extra_info.append("null=True")
@@ -51,7 +62,7 @@ def render_fields_table(fields: dict[str, Any]) -> str:
         extra_str = ", ".join(extra_info) if extra_info else ""
         description_str = help_text or verbose_name
 
-        content += f"| `{field_name}` | {field_type} | {description_str} | {extra_str} |\n"
+        content += f"| `{display_name}` | {field_type} | {description_str} | {extra_str} |\n"
 
     return content
 
@@ -121,35 +132,29 @@ def _create_model_header(name: str, app_label: str, table_name: str, description
 
 def _add_fields_section(model_info: dict[str, Any]) -> str:
     """Add the fields section to the model documentation."""
-    fields = model_info.get("fields", {})
-    non_relationship_fields = {
-        name: info
-        for name, info in fields.items()
-        if info.get("type", "") not in ["ForeignKey", "OneToOneField", "ManyToManyField"]
-    }
-
-    if not non_relationship_fields:
+    column_fields = model_info.get("column_fields", {})
+    if not column_fields:
         return ""
 
-    content = render_fields_table(non_relationship_fields)
-    content += "\n"
-    content += render_choices_tables(non_relationship_fields)
-    content += "\n"
+    content = ""
+
+    column_fields_content = render_column_fields_table(column_fields)
+    if column_fields_content:
+        content += column_fields_content
+        content += "\n"
+
+    choices_content = render_choices_tables(column_fields)
+    if choices_content:
+        content += choices_content
+        content += "\n"
+
     return content
 
 
 def _add_relationships_section(model_info: dict[str, Any]) -> str:
     """Add the relationships section to the model documentation."""
-    fields = model_info.get("fields", {})
-    relationships = model_info.get("relationships", {})
-
-    relationship_fields = {
-        name: info
-        for name, info in fields.items()
-        if info.get("type", "") in ["ForeignKey", "OneToOneField", "ManyToManyField"]
-    }
-
-    if not (relationships or relationship_fields):
+    relationship_fields = model_info.get("relationships", {})
+    if not relationship_fields:
         return ""
 
     content = "## Relationships\n\n"
@@ -157,7 +162,7 @@ def _add_relationships_section(model_info: dict[str, Any]) -> str:
     content += "|-------|------|---------------|\n"
 
     content += _render_relationship_fields(relationship_fields)
-    content += _render_relationships_from_section(relationships)
+    content += _render_relationships_from_section(relationship_fields)
     content += "\n"
 
     return content
@@ -183,13 +188,12 @@ def _render_relationships_from_section(relationships: dict[str, Any]) -> str:
     content = ""
     for rel_name, rel_info in relationships.items():
         rel_type = rel_info.get("type", "Unknown")
-        related_model_full = rel_info.get("related_model", "")
 
-        if related_model_full and "." in related_model_full:
-            related_app, related_model = related_model_full.split(".", 1)
-            model_link = f"[{related_model}](../../{related_app}/{related_model.lower()}/)"
-        else:
-            model_link = related_model_full
+        app_label = rel_info["app_label"]
+        table_name = rel_info["table_name"]
+        verbose_name = rel_info["verbose_name"]
+
+        model_link = f"[{verbose_name.capitalize()}](../../{app_label}/{table_name}/)"
 
         content += f"| `{rel_name}` | {rel_type} | {model_link} | \n"
 

drf_to_mkdoc/utils/model_list_generator.py

@@ -1,22 +1,16 @@
+from html import escape
 from pathlib import Path
 from typing import Any
+from urllib.parse import quote
 
 from django.templatetags.static import static
 
 from drf_to_mkdoc.conf.settings import drf_to_mkdoc_settings
-from drf_to_mkdoc.utils.common import get_app_descriptions
+from drf_to_mkdoc.utils.commons.model_utils import get_app_descriptions
 
 
 def create_models_index(models_data: dict[str, Any], docs_dir: Path) -> None:
     """Create the main models index page that lists all models organized by app."""
-    models_by_app = {}
-    for model_name, model_info in models_data.items():
-        app_name = model_info.get("app_label", model_name.split(".")[0])
-        class_name = model_info.get("name", model_name.split(".")[-1])
-        if app_name not in models_by_app:
-            models_by_app[app_name] = []
-        models_by_app[app_name].append((class_name, model_name, model_info))
-
     stylesheets = [
         "stylesheets/models/variables.css",
         "stylesheets/models/base.css",
@@ -40,17 +34,33 @@ This section contains documentation for all Django models in the system, organiz
 
     app_descriptions = get_app_descriptions()
 
-    for app_name in sorted(models_by_app.keys()):
-        app_desc = app_descriptions.get(app_name, f"{app_name.title()} application models")
-        content += f'<div class="app-header">{app_name.title()} App</div>\n'
+    for app_name, models in sorted(models_data.items()):
+        app_desc = escape(
+            app_descriptions.get(
+                app_name, f"{app_name.replace('_', ' ').title()} application models"
+            )
+        )
+        app_title = escape(app_name.replace("_", " ").title())
+        content += f'<div class="app-header">{app_title} App</div>\n'
         content += f'<div class="app-description">{app_desc}</div>\n\n'
 
         content += '<div class="model-cards">\n'
 
-        for class_name, _model_name, _model_info in sorted(models_by_app[app_name]):
+        model_names = sorted(
+            [
+                (
+                    str(mi.get("verbose_name") or mk),
+                    str(mi.get("table_name") or mk),
+                )
+                for mk, mi in models.items()
+                if isinstance(mi, dict)
+            ],
+            key=lambda x: x[0].casefold(),
+        )
+        for verbose_name, table_name in model_names:
             content += f"""
-            <a href="{app_name}/{class_name.lower()}/"
-             class="model-card">{class_name}</a>\n
+            <a href="{quote(app_name, safe="")}/{quote(table_name, safe="")}/"
+             class="model-card">{escape(verbose_name)}</a>\n
 """
 
         content += "</div>\n\n"