drf-to-mkdoc 0.2.0__py3-none-any.whl → 0.2.2__py3-none-any.whl

drf_to_mkdoc/utils/endpoint_detail_generator.py

@@ -6,24 +6,20 @@ from collections import defaultdict
 from typing import Any
 
 from django.apps import apps
-from django.templatetags.static import static
+from django.template.loader import render_to_string
 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,
 )
-from drf_to_mkdoc.utils.md_generators.query_parameters_generators import (
-    generate_query_parameters_md,
-)
 
 logger = logging.getLogger()
 
@@ -32,17 +28,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 +47,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:
@@ -537,107 +506,93 @@ def format_schema_as_json_example(
     return result
 
 
-def create_endpoint_page(
-    path: str, method: str, endpoint_data: dict[str, Any], components: dict[str, Any]
-) -> str:
-    """Create a documentation page for a single API endpoint."""
-    operation_id = endpoint_data.get("operationId", "")
-    summary = endpoint_data.get("summary", "")
-    description = endpoint_data.get("description", "")
-    parameters = endpoint_data.get("parameters", [])
-    request_body = endpoint_data.get("requestBody", {})
-    responses = endpoint_data.get("responses", {})
-
-    content = _create_endpoint_header(path, method, operation_id, summary, description)
-    content += _add_path_parameters(parameters)
-    content += _add_query_parameters(method, path, operation_id)
-    content += _add_request_body(operation_id, request_body, components)
-    content += _add_responses(operation_id, responses, components)
-
-    return content
-
-
-def _create_endpoint_header(
-    path: str, method: str, operation_id: str, summary: str, description: str
+def _format_schema_for_display(
+    operation_id: str, schema: dict, components: dict, for_response: bool = True
 ) -> str:
-    """Create the header section of the endpoint documentation."""
-    stylesheets = [
-        "stylesheets/endpoints/endpoint-content.css",
-        "stylesheets/endpoints/badges.css",
-        "stylesheets/endpoints/base.css",
-        "stylesheets/endpoints/responsive.css",
-        "stylesheets/endpoints/theme-toggle.css",
-        "stylesheets/endpoints/layout.css",
-        "stylesheets/endpoints/sections.css",
-        "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 and JS directly -->
-{css_links}
-{js_scripts}
-"""
-    content += f"# {method.upper()} {path}\n\n"
-    content += f"{format_method_badge(method)} `{path}`\n\n"
-    content += f"**View class:** {extract_viewset_name_from_operation_id(operation_id)}\n\n"
-
-    if summary:
-        content += f"## Overview\n\n{summary}\n\n"
-    if operation_id:
-        content += f"**Operation ID:** `{operation_id}`\n\n"
-    if description:
-        content += f"{description}\n\n"
-
-    return content
-
-
-def _add_path_parameters(parameters: list[dict]) -> str:
-    """Add path parameters section to the documentation."""
-    path_params = [p for p in parameters if p.get("in") == "path"]
-    if not path_params:
+    """Format schema as a displayable string with JSON example."""
+    if not schema:
         return ""
 
-    content = "## Path Parameters\n\n"
-    content += "| Name | Type | Required | Description |\n"
-    content += "|------|------|----------|-------------|\n"
-
-    for param in path_params:
-        name = param.get("name", "")
-        param_type = param.get("schema", {}).get("type", "string")
-        required = "Yes" if param.get("required", False) else "No"
-        desc = param.get("description", "")
-        content += f"| `{name}` | `{param_type}` | {required} | {desc} |\n"
+    if "$ref" in schema:
+        return format_schema_as_json_example(
+            operation_id, schema["$ref"], components, for_response
+        )
 
-    content += "\n"
-    return content
+    example = schema_to_example_json(operation_id, schema, components, for_response)
+    return f"```json\n{json.dumps(example, indent=2)}\n```"
 
 
-def _add_query_parameters(method: str, path: str, operation_id: str) -> str:
-    """Add query parameters section for list endpoints."""
-    is_list_endpoint = _is_list_endpoint(method, path, operation_id)
-    if not is_list_endpoint:
-        return ""
+def _prepare_response_data(operation_id: str, responses: dict, components: dict) -> list:
+    """Prepare response data for template rendering."""
+    formatted_responses = []
+    for status_code, response_data in responses.items():
+        schema = response_data.get("content", {}).get("application/json", {}).get("schema", {})
+        formatted_responses.append(
+            {
+                "status_code": status_code,
+                "description": response_data.get("description", ""),
+                "example": _format_schema_for_display(operation_id, schema, components, True),
+            }
+        )
+    return formatted_responses
 
-    query_params = extract_query_parameters_from_view(operation_id)
-    _add_custom_parameters(operation_id, query_params)
 
-    query_params_content = generate_query_parameters_md(query_params)
-    if query_params_content and not query_params_content.startswith("**Error:**"):
-        return "## Query Parameters\n\n" + query_params_content
+def create_endpoint_page(
+    path: str, method: str, endpoint_data: dict[str, Any], components: dict[str, Any]
+) -> str:
+    """Create a documentation page for a single API endpoint."""
+    operation_id = endpoint_data.get("operationId", "")
+    request_schema = (
+        endpoint_data.get("requestBody", {})
+        .get("content", {})
+        .get("application/json", {})
+        .get("schema")
+    )
 
-    return ""
+    # Prepare template context
+    context = {
+        "path": path,
+        "method": method,
+        "operation_id": operation_id,
+        "summary": endpoint_data.get("summary", ""),
+        "description": endpoint_data.get("description", ""),
+        "viewset_name": extract_viewset_name_from_operation_id(operation_id),
+        "path_params": [
+            p for p in endpoint_data.get("parameters", []) if p.get("in") == "path"
+        ],
+        "request_body": endpoint_data.get("requestBody", {}),
+        "request_example": _format_schema_for_display(
+            operation_id, request_schema, components, False
+        )
+        if request_schema
+        else "",
+        "responses": _prepare_response_data(
+            operation_id, endpoint_data.get("responses", {}), components
+        ),
+        "stylesheets": [
+            "stylesheets/endpoints/endpoint-content.css",
+            "stylesheets/endpoints/badges.css",
+            "stylesheets/endpoints/base.css",
+            "stylesheets/endpoints/responsive.css",
+            "stylesheets/endpoints/theme-toggle.css",
+            "stylesheets/endpoints/layout.css",
+            "stylesheets/endpoints/sections.css",
+            "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}/",
+    }
+
+    # Add query parameters if it's a list endpoint
+    if _is_list_endpoint(method, path, operation_id):
+        query_params = extract_query_parameters_from_view(operation_id)
+        _add_custom_parameters(operation_id, query_params)
+        context["query_parameters"] = query_params
+
+    return render_to_string("endpoints/detail/base.html", context)
 
 
 def _is_list_endpoint(method: str, path: str, operation_id: str) -> bool:
@@ -659,77 +614,6 @@ def _add_custom_parameters(operation_id: str, query_params: dict) -> None:
         query_params[queryparam_type].append(parameter["name"])
 
 
-def _add_request_body(operation_id: str, request_body: dict, components: dict[str, Any]) -> str:
-    """Add request body section to the documentation."""
-    if not request_body:
-        return ""
-
-    content = "## Request Body\n\n"
-    req_schema = request_body.get("content", {}).get("application/json", {}).get("schema")
-
-    if req_schema and "$ref" in req_schema:
-        content += (
-            format_schema_as_json_example(
-                operation_id, req_schema["$ref"], components, for_response=False
-            )
-            + "\n"
-        )
-
-    return content
-
-
-def _add_responses(operation_id: str, responses: dict, components: dict[str, Any]) -> str:
-    """Add responses section to the documentation."""
-    if not responses:
-        return ""
-
-    content = "## Responses\n\n"
-    for status_code, response_data in responses.items():
-        content += _format_single_response(operation_id, status_code, response_data, components)
-
-    return content
-
-
-def _format_single_response(
-    operation_id: str, status_code: str, response_data: dict, components: dict[str, Any]
-) -> str:
-    """Format a single response entry."""
-    content = f"### {status_code}\n\n"
-
-    if desc := response_data.get("description", ""):
-        content += f"{desc}\n\n"
-
-    resp_schema = response_data.get("content", {}).get("application/json", {}).get("schema", {})
-
-    content += _format_response_schema(operation_id, resp_schema, components)
-    return content
-
-
-def _format_response_schema(
-    operation_id: str, resp_schema: dict, components: dict[str, Any]
-) -> str:
-    """Format the response schema as JSON example."""
-    if "$ref" in resp_schema:
-        return (
-            format_schema_as_json_example(
-                operation_id, resp_schema["$ref"], components, for_response=True
-            )
-            + "\n"
-        )
-    if resp_schema.get("type") == "array" and "$ref" in resp_schema.get("items", {}):
-        item_ref = resp_schema["items"]["$ref"]
-        return (
-            format_schema_as_json_example(operation_id, item_ref, components, for_response=True)
-            + "\n"
-        )
-    content = "```json\n"
-    content += json.dumps(
-        schema_to_example_json(operation_id, resp_schema, components), indent=2
-    )
-    content += "\n```\n"
-    return content
-
-
 def parse_endpoints_from_schema(paths: dict[str, Any]) -> dict[str, list[dict[str, Any]]]:
     """Parse endpoints from OpenAPI schema and organize by app"""
 

drf_to_mkdoc/utils/endpoint_list_generator.py

@@ -1,219 +1,84 @@
 from pathlib import Path
 from typing import Any
 
+from django.template.loader import render_to_string
 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:
     def __init__(self, active_filters: list[str] | None = None):
-        self.active_filters = set(
-            active_filters
-            or [
-                "method",
-                "path",
-                "app",
-                "models",
-                "auth",
-                "roles",
-                "content_type",
-                "params",
-                "schema",
-                "pagination",
-                "ordering",
-                "search",
-                "tags",
-            ]
-        )
-
-    def create_endpoint_card(
-        self, endpoint: dict[str, Any], app_name: str, viewset_name: str
-    ) -> str:
-        method = endpoint["method"]
-        path = endpoint["path"]
-        filename = endpoint["filename"]
-        view_class = extract_viewset_from_operation_id(endpoint["operation_id"])
-
-        link_url = f"{app_name}/{viewset_name.lower()}/{filename}".replace(".md", "/index.html")
-        data_attrs = f"""
-            data-method="{method.lower()}"
-            data-path="{path.lower()}"
-            data-app="{app_name.lower()}"
-            data-auth="{str(endpoint.get("auth_required", False)).lower()}"
-            data-pagination="{str(endpoint.get("pagination_support", False)).lower()}"
-            data-search="{str(bool(getattr(view_class, "search_fields", []))).lower()}"
-            data-ordering="{str(endpoint.get("ordering_support", False)).lower()}"
-            data-models="{" ".join(endpoint.get("related_models", [])).lower()}"
-            data-roles="{" ".join(endpoint.get("permission_roles", [])).lower()}"
-            data-content-type="{endpoint.get("content_type", "").lower()}"
-            data-tags="{" ".join(endpoint.get("tags", [])).lower()}"
-            data-schema="{" ".join(endpoint.get("schema_fields", [])).lower()}"
-            data-params="{" ".join(endpoint.get("query_parameters", [])).lower()}"
-        """.strip()
-
-        return f"""
-    <a href="{link_url}" class="endpoint-card" {data_attrs}>
-        <span class="method-badge method-{method.lower()}">{method}</span>
-        <span class="endpoint-path">{path}</span>
-    </a>
-    """
-
-    def create_filter_section(self) -> str:
-        filter_fields = {
-            "method": """<div class="filter-group">
-                <label class="filter-label">HTTP Method</label>
-                <select id="filter-method" class="filter-select">
-                    <option value="">All</option>
-                    <option value="get">GET</option>
-                    <option value="post">POST</option>
-                    <option value="put">PUT</option>
-                    <option value="patch">PATCH</option>
-                    <option value="delete">DELETE</option>
-                </select>
-            </div>""",
-            "path": """<div class="filter-group">
-                <label class="filter-label">Endpoint Path</label>
-                <input type="text" id="filter-path" class="filter-input"
-                placeholder="Search path...">
-            </div>""",
-            "app": """<div class="filter-group">
-                <label class="filter-label">Django App</label>
-                <select id="filter-app" class="filter-select">
-                    <option value="">All</option>
-                    <!-- Dynamically filled -->
-                </select>
-            </div>""",
-            "models": """<div class="filter-group">
-                <label class="filter-label">Related Models</label>
-                <input type="text" id="filter-models" class="filter-input">
-            </div>""",
-            "auth": """<div class="filter-group">
-                <label class="filter-label">Authentication Required</label>
-                <select id="filter-auth" class="filter-select">
-                    <option value="">All</option>
-                    <option value="true">Yes</option>
-                    <option value="false">No</option>
-                </select>
-            </div>""",
-            "roles": """<div class="filter-group">
-                <label class="filter-label">Permission Roles</label>
-                <input type="text" id="filter-roles" class="filter-input">
-            </div>""",
-            "content_type": """<div class="filter-group">
-                <label class="filter-label">Content Type</label>
-                <input type="text" id="filter-content-type" class="filter-input">
-            </div>""",
-            "params": """<div class="filter-group">
-                <label class="filter-label">Query Parameters</label>
-                <input type="text" id="filter-params" class="filter-input">
-            </div>""",
-            "schema": """<div class="filter-group">
-                <label class="filter-label">Schema Fields</label>
-                <input type="text" id="filter-schema" class="filter-input">
-            </div>""",
-            "pagination": """<div class="filter-group">
-                <label class="filter-label">Pagination Support</label>
-                <select id="filter-pagination" class="filter-select">
-                    <option value="">All</option>
-                    <option value="true">Yes</option>
-                    <option value="false">No</option>
-                </select>
-            </div>""",
-            "ordering": """<div class="filter-group">
-                <label class="filter-label">Ordering Support</label>
-                <select id="filter-ordering" class="filter-select">
-                    <option value="">All</option>
-                    <option value="true">Yes</option>
-                    <option value="false">No</option>
-                </select>
-            </div>""",
-            "search": """<div class="filter-group">
-                <label class="filter-label">Search Support</label>
-                <select id="filter-search" class="filter-select">
-                    <option value="">All</option>
-                    <option value="true">Yes</option>
-                    <option value="false">No</option>
-                </select>
-            </div>""",
-            "tags": """<div class="filter-group">
-                <label class="filter-label">Tags</label>
-                <input type="text" id="filter-tags" class="filter-input">
-            </div>""",
-        }
-
-        fields_html = "\n".join(
-            [html for key, html in filter_fields.items() if (key in self.active_filters)]
-        )
-
-        return f"""
-        <div class="filter-sidebar collapsed" id="filterSidebar">
-            <h3 class="filter-title">🔍 Filters</h3>
-            <div class="filter-grid">
-                {fields_html}
-            </div>
-
-            <div class="filter-actions">
-                <button class="filter-apply" onclick="applyFilters()">Apply</button>
-                <button class="filter-clear" onclick="clearFilters()">Clear</button>
-            </div>
-
-            <div class="filter-results">Showing 0 endpoints</div>
-        </div>
-        """
+        self.active_filters = active_filters or [
+            "method",
+            "path",
+            "app",
+            "models",
+            "auth",
+            "roles",
+            "content_type",
+            "params",
+            "schema",
+            "pagination",
+            "ordering",
+            "search",
+            "tags",
+        ]
 
     def create_endpoints_index(
         self, endpoints_by_app: dict[str, list[dict[str, Any]]], docs_dir: Path
     ) -> None:
+        prefix_path = f"{drf_to_mkdoc_settings.PROJECT_NAME}/"
         stylesheets = [
-            "stylesheets/endpoints/variables.css",
-            "stylesheets/endpoints/base.css",
-            "stylesheets/endpoints/theme-toggle.css",
-            "stylesheets/endpoints/filter-section.css",
-            "stylesheets/endpoints/layout.css",
-            "stylesheets/endpoints/endpoints-grid.css",
-            "stylesheets/endpoints/badges.css",
-            "stylesheets/endpoints/endpoint-content.css",
-            "stylesheets/endpoints/tags.css",
-            "stylesheets/endpoints/sections.css",
-            "stylesheets/endpoints/stats.css",
-            "stylesheets/endpoints/loading.css",
-            "stylesheets/endpoints/animations.css",
-            "stylesheets/endpoints/responsive.css",
-            "stylesheets/endpoints/accessibility.css",
-            "stylesheets/endpoints/fixes.css",
+            static(prefix_path + path)
+            for path in [
+                "stylesheets/endpoints/variables.css",
+                "stylesheets/endpoints/base.css",
+                "stylesheets/endpoints/theme-toggle.css",
+                "stylesheets/endpoints/filter-section.css",
+                "stylesheets/endpoints/layout.css",
+                "stylesheets/endpoints/endpoints-grid.css",
+                "stylesheets/endpoints/badges.css",
+                "stylesheets/endpoints/endpoint-content.css",
+                "stylesheets/endpoints/tags.css",
+                "stylesheets/endpoints/sections.css",
+                "stylesheets/endpoints/stats.css",
+                "stylesheets/endpoints/loading.css",
+                "stylesheets/endpoints/animations.css",
+                "stylesheets/endpoints/responsive.css",
+                "stylesheets/endpoints/accessibility.css",
+                "stylesheets/endpoints/fixes.css",
+            ]
         ]
 
         scripts = [
-            "javascripts/endpoints-filter.js",
+            static(prefix_path + "javascripts/endpoints-filter.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"""# API Endpoints
-<!-- inject CSS and JS directly -->
-{css_links}
-{js_scripts}
-
-<div class="main-content">
-        """
-        content += self.create_filter_section()
+        # Process endpoints to add view_class
+        processed_endpoints = {}
+        for app_name, app_endpoints in endpoints_by_app.items():
+            processed_endpoints[app_name] = []
+            for endpoint in app_endpoints:
+                processed_endpoint = endpoint.copy()
+                processed_endpoint["view_class"] = extract_viewset_from_operation_id(
+                    endpoint["operation_id"]
+                )
+                processed_endpoint["link_url"] = (
+                    f"{app_name}/{processed_endpoint['viewset'].lower()}/{processed_endpoint['filename'].replace('.md', '/index.html')}"
+                )
+                processed_endpoints[app_name].append(processed_endpoint)
+
+        context = {
+            "stylesheets": stylesheets,
+            "scripts": scripts,
+            "endpoints_by_app": processed_endpoints,
+            "active_filters": self.active_filters,
+        }
 
-        for app_name, endpoints in endpoints_by_app.items():
-            content += f'<h2>{app_name.title()}</h2>\n<div class="endpoints-grid">\n'
-            for endpoint in endpoints:
-                viewset = endpoint["viewset"]
-                content += self.create_endpoint_card(endpoint, app_name, viewset)
-            content += "</div>\n"
+        content = render_to_string("endpoints/list/base.html", context)
 
-        content += "</div>\n"
         output_path = docs_dir / "endpoints" / "index.md"
         output_path.parent.mkdir(parents=True, exist_ok=True)
         with Path(output_path).open("w", encoding="utf-8") as f: