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

drf_to_mkdoc/templates/try-out/response-modal.html

@@ -0,0 +1,149 @@
+<!-- Response Modal -->
+<div 
+    id="responseModal" 
+    class="response-modal" 
+    role="dialog" 
+    aria-modal="true" 
+    aria-labelledby="responseTitle"
+    aria-describedby="responseDescription"
+>
+    <div class="modal-overlay" onclick="TryOutSidebar.closeResponseModal()"></div>
+    <div class="modal-content">
+        <!-- Modal Header -->
+        <div class="modal-header">
+            <div class="header-content">
+                <h3 id="responseTitle">API Response</h3>
+                <span id="responseDescription" class="visually-hidden">Displays the API response details and content</span>
+                <div class="header-actions">
+                    <button 
+                        class="action-btn" 
+                        onclick="copyResponse()" 
+                        aria-label="Copy response"
+                        data-tooltip="Copy to clipboard"
+                    >
+                        <span class="icon">📋</span>
+                    </button>
+                    <button 
+                        class="action-btn" 
+                        onclick="downloadResponse()" 
+                        aria-label="Download response"
+                        data-tooltip="Download as JSON"
+                    >
+                        <span class="icon">💾</span>
+                    </button>
+                    <button 
+                        class="modal-close" 
+                        aria-label="Close response modal" 
+                        onclick="TryOutSidebar.closeResponseModal()"
+                    >
+                        <span class="icon">✕</span>
+                    </button>
+                </div>
+            </div>
+        </div>
+
+        <!-- Response Stats -->
+        <div class="response-stats">
+            <div class="stat-group">
+                <div class="stat-item">
+                    <span class="stat-label">Status</span>
+                    <span class="status-badge" id="modalStatusBadge"></span>
+                </div>
+                <div class="stat-item">
+                    <span class="stat-label">Time</span>
+                    <span class="stat-value" id="responseTime">0 ms</span>
+                </div>
+                <div class="stat-item">
+                    <span class="stat-label">Size</span>
+                    <span class="stat-value" id="responseSize">0 KB</span>
+                </div>
+            </div>
+            <div class="response-info" id="responseInfo"></div>
+        </div>
+
+        <!-- Response Content -->
+        <div class="modal-body">
+            <!-- Response Tabs -->
+            <div class="response-tabs" role="tablist">
+                <button 
+                    class="tab active" 
+                    role="tab" 
+                    aria-selected="true"
+                    aria-controls="responseBody"
+                    data-tab="body"
+                >
+                    <span class="icon">📄</span>
+                    Response
+                </button>
+                <button 
+                    class="tab" 
+                    role="tab"
+                    aria-selected="false"
+                    aria-controls="responseHeaders"
+                    data-tab="headers"
+                >
+                    <span class="icon">📋</span>
+                    Headers
+                </button>
+            </div>
+
+            <!-- Response Body Tab -->
+            <div 
+                id="responseBody" 
+                class="tab-content active" 
+                role="tabpanel"
+            >
+                <div class="response-toolbar">
+                    <div class="toolbar-group">
+                        <button 
+                            class="tool-btn" 
+                            onclick="formatResponse()"
+                            data-tooltip="Format JSON"
+                        >
+                            <span class="icon">🔧</span>
+                        </button>
+                        <button 
+                            class="tool-btn" 
+                            onclick="collapseAll()"
+                            data-tooltip="Collapse all"
+                        >
+                            <span class="icon">📦</span>
+                        </button>
+                        <button 
+                            class="tool-btn" 
+                            onclick="expandAll()"
+                            data-tooltip="Expand all"
+                        >
+                            <span class="icon">📂</span>
+                        </button>
+                    </div>
+                </div>
+                <div class="response-viewer" role="region" aria-live="polite">
+                    <div class="response-content" id="modalResponseBody" tabindex="0"></div>
+                </div>
+            </div>
+
+            <!-- Response Headers Tab -->
+            <div 
+                id="responseHeaders" 
+                class="tab-content" 
+                role="tabpanel"
+            >
+                <div class="headers-list" id="responseHeadersList"></div>
+            </div>
+
+        </div>
+    </div>
+</div>
+
+<script>
+    // Update event handlers to use the ResponseModalManager
+    document.addEventListener('DOMContentLoaded', function() {
+        // Update button click handlers
+        document.querySelector('button[onclick="copyResponse()"]').setAttribute('onclick', 'ResponseModalManager.copyResponse()');
+        document.querySelector('button[onclick="downloadResponse()"]').setAttribute('onclick', 'ResponseModalManager.downloadResponse()');
+        document.querySelector('button[onclick="formatResponse()"]').setAttribute('onclick', 'ResponseModalManager.formatResponse()');
+        document.querySelector('button[onclick="collapseAll()"]').setAttribute('onclick', 'ResponseModalManager.collapseAll()');
+        document.querySelector('button[onclick="expandAll()"]').setAttribute('onclick', 'ResponseModalManager.expandAll()');
+    });
+</script>

drf_to_mkdoc/templatetags/custom_filters.py

@@ -1,5 +1,6 @@
 import html
 import json
+import re
 
 from django import template
 from django.templatetags.static import static as django_static
@@ -113,4 +114,35 @@ def format_json(value):
     elif isinstance(value, dict | list):
         value = json.dumps(value, indent=2)
 
-    return mark_safe(value)  # noqa: S308
+    return mark_safe(f"```json\n{value}\n```")  # noqa: S308
+
+
+@register.filter
+def extract_json_from_markdown(value):
+    """Extract JSON content from markdown code blocks"""
+    if not isinstance(value, str):
+        return ""
+
+    # Look for ```json code blocks
+
+    json_pattern = r"```json\s*\n(.*?)\n```"
+    matches = re.findall(json_pattern, value, re.DOTALL)
+
+    if matches:
+        return matches[0].strip()
+
+    # Fallback: look for any code block
+    code_pattern = r"```\s*\n(.*?)\n```"
+    matches = re.findall(code_pattern, value, re.DOTALL)
+
+    if matches:
+        content = matches[0].strip()
+        # Try to validate if it's JSON
+        try:
+            json.loads(content)
+        except (json.JSONDecodeError, TypeError):
+            pass
+        else:
+            return content
+
+    return ""

drf_to_mkdoc/utils/commons/schema_utils.py

@@ -1,8 +1,9 @@
 import json
+from copy import deepcopy
+from functools import lru_cache
 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
@@ -21,16 +22,6 @@ class QueryParamTypeError(Exception):
     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
@@ -56,7 +47,6 @@ def get_custom_schema():
                         "search_fields",
                         "filter_fields",
                         "ordering_fields",
-                        "filter_backends",
                         "pagination_fields",
                     }
                 ):
@@ -153,16 +143,17 @@ def _apply_custom_overrides(
                 target_schema[key] = custom_value
 
 
+@lru_cache(maxsize=1)
 def get_schema():
     base_schema = SchemaGenerator().get_schema(request=None, public=True)
     custom_data = get_custom_schema()
     if not custom_data:
-        return base_schema
+        return deepcopy(base_schema)
 
     operation_map = _build_operation_map(base_schema)
     _apply_custom_overrides(base_schema, operation_map, custom_data)
 
-    return base_schema
+    return deepcopy(base_schema)
 
 
 class OperationExtractor:

drf_to_mkdoc/utils/endpoint_detail_generator.py

@@ -366,10 +366,17 @@ def _enhance_method_field_schema(_operation_id, schema: dict, _components: dict)
 
 def _resolve_schema_reference(schema: dict, components: dict) -> dict:
     """Resolve $ref references in schema."""
-    if "$ref" in schema:
-        ref = schema["$ref"]
-        return components.get("schemas", {}).get(ref.split("/")[-1], {})
-    return schema
+    if "$ref" not in schema:
+        return schema
+
+    ref = schema["$ref"]
+    target = components.get("schemas", {}).get(ref.split("/")[-1], {})
+    # Work on a copy to avoid mutating components
+    resolved = dict(target) if isinstance(target, dict) else {}
+    for key, value in schema.items():
+        if key != "$ref":
+            resolved[key] = value
+    return resolved
 
 
 def _handle_all_of_schema(schema: dict, components: dict, _for_response: bool) -> dict:
@@ -401,16 +408,22 @@ def _handle_all_of_schema(schema: dict, components: dict, _for_response: bool) -
 
 def _get_explicit_value(schema: dict):
     """Get explicit value from schema (enum, example, or default)."""
-    # Ensure schema is a dictionary
     if not isinstance(schema, dict):
         return None
 
     if "enum" in schema:
         return schema["enum"][0]
+
     if "example" in schema:
         return schema["example"]
+
     if "default" in schema:
+        # For array types with items schema, don't use empty default
+        # Let the generator create a proper example instead
+        if schema.get("type") == "array" and "items" in schema:
+            return None
         return schema["default"]
+
     return None
 
 
@@ -499,11 +512,7 @@ def format_schema_as_json_example(
     if description:
         result += f"{description}\n\n"
 
-    result += "```json\n"
-    result += json.dumps(example_json, indent=2)
-    result += "\n```\n"
-
-    return result
+    return json.dumps(example_json, indent=2)
 
 
 def _format_schema_for_display(
@@ -518,22 +527,122 @@ def _format_schema_for_display(
             operation_id, schema["$ref"], components, for_response
         )
 
-    example = schema_to_example_json(operation_id, schema, components, for_response)
-    return f"```json\n{json.dumps(example, indent=2)}\n```"
+    return schema_to_example_json(operation_id, schema, components, for_response)
+
+
+def _generate_field_value(
+    field_name: str,
+    prop_schema: dict,
+    operation_id: str,
+    components: dict,
+    is_response: bool = True,
+) -> Any:
+    """Generate a realistic value for a specific field based on its name and schema."""
+    # Get field-specific generator from settings
+    field_generator = get_field_generator(field_name)
+
+    if field_generator:
+        return field_generator(prop_schema)
+
+    # Fallback to schema-based generation
+    return schema_to_example_json(operation_id, prop_schema, components, is_response)
+
+
+def get_field_generator(field_name: str):
+    """Get appropriate generator function for a field name from settings."""
+    return drf_to_mkdoc_settings.FIELD_GENERATORS.get(field_name.lower())
+
+
+def _generate_examples(operation_id: str, schema: dict, components: dict) -> list:
+    """Generate examples for a schema."""
+
+    if "$ref" in schema:
+        schema = _resolve_schema_reference(schema, components)
+
+    examples = []
+
+    # Handle object with array properties
+    if schema.get("type") == "object" and "properties" in schema:
+        empty_example = {}
+        populated_example = {}
+        has_array_default = False
+
+        # Check for array fields with default=[]
+        for _prop_name, prop_schema in schema["properties"].items():
+            resolved_prop_schema = (
+                _resolve_schema_reference(prop_schema, components)
+                if "$ref" in prop_schema
+                else prop_schema
+            )
+            if (
+                resolved_prop_schema.get("type") == "array"
+                and resolved_prop_schema.get("default") == []
+            ):
+                has_array_default = True
+                break
+
+        # Generate examples
+        for prop_name, prop_schema in schema["properties"].items():
+            resolved_prop_schema = (
+                _resolve_schema_reference(prop_schema, components)
+                if "$ref" in prop_schema
+                else prop_schema
+            )
+
+            if (
+                resolved_prop_schema.get("type") == "array"
+                and resolved_prop_schema.get("default") == []
+            ):
+                empty_example[prop_name] = []
+                items_schema = resolved_prop_schema.get("items", {})
+                populated_example[prop_name] = [
+                    _generate_field_value(
+                        prop_name, items_schema, operation_id, components, True
+                    )
+                ]
+            else:
+                value = _generate_field_value(
+                    prop_name, resolved_prop_schema, operation_id, components, True
+                )
+                empty_example[prop_name] = value
+                populated_example[prop_name] = value
+
+        if has_array_default:
+            examples.append(empty_example)
+            examples.append(populated_example)
+        else:
+            examples.append(empty_example)
+
+    # Handle array field with default=[]
+    elif schema.get("type") == "array" and schema.get("default") == []:
+        examples.append([])
+        items_schema = schema.get("items", {})
+        populated_example = [
+            _generate_field_value("items", items_schema, operation_id, components, True)
+        ]
+        examples.append(populated_example)
+    else:
+        example = _generate_field_value("root", schema, operation_id, components, True)
+        examples.append(example)
+
+    return examples
 
 
 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),
-            }
-        )
+
+        examples = _generate_examples(operation_id, schema, components)
+
+        formatted_response = {
+            "status_code": status_code,
+            "description": response_data.get("description", ""),
+            "examples": examples,
+        }
+        formatted_responses.append(formatted_response)
     return formatted_responses
 
 
@@ -580,9 +689,17 @@ def create_endpoint_page(
             "stylesheets/endpoints/animations.css",
             "stylesheets/endpoints/accessibility.css",
             "stylesheets/endpoints/loading.css",
-            "stylesheets/endpoints/try-out-sidebar.css",
+            "stylesheets/try-out/main.css",
+        ],
+        "scripts": [
+            "javascripts/try-out/modal.js",
+            "javascripts/try-out/response-modal.js",
+            "javascripts/try-out/tabs.js",
+            "javascripts/try-out/form-manager.js",
+            "javascripts/try-out/request-executor.js",
+            "javascripts/try-out/suggestions.js",
+            "javascripts/try-out/main.js",
         ],
-        "scripts": ["javascripts/try-out-sidebar.js"],
         "prefix_path": f"{drf_to_mkdoc_settings.PROJECT_NAME}/",
     }
 
@@ -590,6 +707,9 @@ def create_endpoint_page(
     if _is_list_endpoint(method, path, operation_id):
         query_params = extract_query_parameters_from_view(operation_id)
         _add_custom_parameters(operation_id, query_params)
+        for key, value in query_params.items():
+            # Prevent duplicates while preserving order
+            query_params[key] = list(dict.fromkeys(value))
         context["query_parameters"] = query_params
 
     return render_to_string("endpoints/detail/base.html", context)

drf_to_mkdoc/utils/extractors/query_parameter_extractors.py

@@ -11,7 +11,6 @@ def extract_query_parameters_from_view(operation_id: str) -> dict[str, Any]:
             "search_fields": [],
             "filter_fields": [],
             "ordering_fields": [],
-            "filter_backends": [],
             "pagination_fields": [],
         }
 
@@ -19,7 +18,6 @@ def extract_query_parameters_from_view(operation_id: str) -> dict[str, Any]:
         "search_fields": extract_query_parameters_from_view_search_fields(view_class),
         "filter_fields": extract_query_parameters_from_view_filter_fields(view_class),
         "ordering_fields": extract_query_parameters_from_view_ordering_fields(view_class),
-        "filter_backends": extract_query_parameters_from_view_filter_backends(view_class),
         "pagination_fields": extract_query_parameters_from_view_pagination_fields(view_class),
     }
 
@@ -62,19 +60,6 @@ def extract_query_parameters_from_view_ordering_fields(view_class: Any) -> list[
     return ordering_fields
 
 
-def extract_query_parameters_from_view_filter_backends(view_class: Any) -> list[str]:
-    """Extract filter backends from a Django view class"""
-    if not view_class:
-        return []
-
-    filter_backends = []
-    if hasattr(view_class, "filter_backends") and view_class.filter_backends:
-        for backend in view_class.filter_backends:
-            filter_backends.append(getattr(backend, "__name__", str(backend)))
-
-    return filter_backends
-
-
 def extract_query_parameters_from_view_pagination_fields(view_class: Any) -> list[str]:
     """Extract pagination fields from a Django view class"""
     if not view_class:

{drf_to_mkdoc-0.2.2.dist-info → drf_to_mkdoc-0.2.4.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: drf-to-mkdoc
-Version: 0.2.2
+Version: 0.2.4
 Summary: Generate Markdown API docs from Django/DRF OpenAPI schema for MkDocs
 Author-email: Hossein Shayesteh <shayestehhs1@gmail.com>
 Maintainer-email: Hossein Shayesteh <shayestehhs1@gmail.com>
@@ -56,6 +56,8 @@ Generate beautiful, interactive Markdown API documentation from Django REST Fram
 - **Zero-hassle docs**: Beautiful, always-in-sync API docs straight from your codebase
 - **Model deep dive**: Auto-generated model pages with fields, relationships, and choices
 - **Lightning-fast discovery**: Interactive endpoint index with powerful filters and search
+- **Try-it-out**: Interactive API testing directly in the documentation with request/response examples
+- **AI-powered**: Optional AI-generated documentation with custom field generators(Wait for it...)
 - **DRF-native**: Works with DRF Spectacular; no custom schema wiring needed
 - **MkDocs Material**: Looks great out of the box with the Material theme
 
@@ -76,7 +78,7 @@ INSTALLED_APPS = [
 
 # Required for OpenAPI schema generation
 REST_FRAMEWORK = {
-    'DEFAULT_SCHEMA_CLASS': 'drf_to_mkdoc.utils.schema.AutoSchema',  # Use our custom AutoSchema
+    'DEFAULT_SCHEMA_CLASS': 'drf_to_mkdoc.utils.schema.AutoSchema',
 }
 
 SPECTACULAR_SETTINGS = {
@@ -99,6 +101,12 @@ DRF_TO_MKDOC = {
     # 'MODEL_DOCS_FILE': 'docs/model-docs.json',
     # 'DOC_CONFIG_FILE': 'docs/configs/doc_config.json',
     # 'CUSTOM_SCHEMA_FILE': 'docs/configs/custom_schema.json',
+    # 'FIELD_GENERATORS': {
+    #     'email': 'faker.email',
+    #     'name': 'faker.name',
+    #     'created_at': 'datetime.now',
+    # },
+    # 'ENABLE_AI_DOCS': False,
 }
 ```
 
@@ -111,18 +119,54 @@ DRF_TO_MKDOC = {
 python manage.py build_docs --settings=docs_settings
 ```
 
+### Configuration Options
+
+The `DRF_TO_MKDOC` setting supports several configuration options:
+
+- **`DJANGO_APPS`** (required): List of Django app names to process
+- **`DOCS_DIR`**: Directory where docs will be generated (default: `docs`)
+- **`CONFIG_DIR`**: Directory for configuration files (default: `docs/configs`)
+- **`FIELD_GENERATORS`**: Custom field value generators for better examples
+- **`ENABLE_AI_DOCS`**: Enable AI-powered documentation features (default: `False`)
+- **`PATH_PARAM_SUBSTITUTE_FUNCTION`**: Custom function for path parameter substitution
+- **`PATH_PARAM_SUBSTITUTE_MAPPING`**: Mapping for path parameter substitution
+
 ## Available Commands
 
 - `build_docs`: Build the complete documentation site with MkDocs
 - `build_endpoint_docs`: Build endpoint documentation from OpenAPI schema
 - `build_model_docs`: Build model documentation from model JSON data
 - `extract_model_data`: Extract model data from Django model introspection and save as JSON
+- `generate_doc_json`: Generate JSON context for new API endpoints to be documented
 - `update_doc_schema`: Update the final schema by copying the documented schema
 
 ## What you get
 
 See a detailed overview of generated files in `docs/structure.md` and a feature breakdown in `docs/features.md`.
 
+## Key Features
+
+### 🚀 Interactive API Testing (Try-Out)
+- **Live API testing**: Test endpoints directly from the documentation
+- **Request builder**: Interactive forms for parameters, headers, and request body
+- **Response viewer**: Real-time response display with syntax highlighting
+- **Floating action button**: Easy access to testing interface
+- **Multiple examples**: Support for both empty and populated response examples
+
+### 🤖 AI-Powered Documentation
+- **Custom field generators**: Define custom value generators for specific fields
+- **AI documentation**: Optional AI-generated documentation with context analysis
+- **Smart examples**: Enhanced example generation for better API understanding
+
+### 📊 Advanced Filtering & Search
+- **Multi-criteria filtering**: Filter by app, HTTP method, path, and search terms
+- **Real-time search**: Instant search across all endpoints
+- **Smart suggestions**: Auto-complete for query parameters and field names
+
+### 🎨 Beautiful UI
+- **Material Design**: Modern, responsive interface with dark/light themes
+- **Interactive elements**: Hover effects, animations, and smooth transitions
+- **Mobile-friendly**: Fully responsive design for all devices
 
 ## How it works
 
@@ -167,13 +211,29 @@ drf-to-mkdoc/
 │   │       ├── build_endpoint_docs.py  # Build endpoint documentation
 │   │       ├── build_model_docs.py     # Build model documentation
 │   │       ├── extract_model_data.py   # Extract model data from Django
+│   │       ├── generate_doc_json.py    # Generate JSON context for AI docs
 │   │       └── update_doc_schema.py    # Schema updates
+│   ├── static/
+│   │   └── drf-to-mkdoc/
+│   │       ├── javascripts/
+│   │       │   ├── try-out/            # Interactive API testing
+│   │       │   └── endpoints-filter.js # Endpoint filtering
+│   │       └── stylesheets/            # CSS for styling
+│   ├── templates/
+│   │   ├── endpoints/                  # Endpoint documentation templates
+│   │   ├── model_detail/               # Model documentation templates
+│   │   └── try-out/                    # Interactive testing templates
 │   └── utils/
-│       ├── common.py        # Shared utilities
-│       ├── endpoint_generator.py  # Endpoint documentation
-│       ├── model_generator.py     # Model documentation
-│       └── extractors/      # Query parameter extraction
-├── pyproject.toml           # Project configuration
+│       ├── ai_tools/                   # AI-powered documentation features
+│       ├── commons/                    # Shared utilities
+│       ├── extractors/                 # Query parameter extraction
+│       ├── endpoint_detail_generator.py
+│       ├── endpoint_list_generator.py
+│       ├── model_detail_generator.py
+│       ├── model_list_generator.py
+│       └── schema.py
+├── docs/                      # Generated documentation
+├── pyproject.toml            # Project configuration
 └── README.md
 ```
 
@@ -232,5 +292,4 @@ your-project/
 
 ## Contributing
 
-See [CONTRIBUTING.md](CONTRIBUTING.md) for detailed contribution guidelines. 
-This will ensure that only the source configuration and scripts are versioned, while the generated documentation is excluded.
+See [CONTRIBUTING.md](CONTRIBUTING.md) for detailed contribution guidelines.