Merge 6bb4871 into c0939a7

Author: noliveleger

kobo/apps/audit_log/views.py

@@ -15,6 +15,7 @@
 )
 from kpi.paginators import FastPagination, Paginated
 from kpi.permissions import IsAuthenticated
+from kpi.renderers import BasicHTMLRenderer
 from kpi.tasks import export_task_in_background
 from kpi.utils.schema_extensions.markdown import read_md
 from kpi.utils.schema_extensions.response import (
@@ -368,7 +369,10 @@ class BaseAccessLogsExportViewSet(viewsets.ViewSet):
     # the schema, even if the viewset doesn’t override the renderers or return content
     # that would need them. Without this, it falls back to the default DRF settings,
     # which may not reflect the actual behavior of the viewset.
-    renderer_classes = (JSONRenderer,)
+    renderer_classes = (
+        JSONRenderer,
+        BasicHTMLRenderer,
+    )
 
     def create_task(self, request, get_all_logs):
 

kobo/apps/organizations/views.py

@@ -10,7 +10,6 @@
 )
 from rest_framework import status, viewsets
 from rest_framework.decorators import action
-from rest_framework.renderers import JSONRenderer
 from rest_framework.request import Request
 from rest_framework.response import Response
 
@@ -202,9 +201,6 @@ class OrganizationViewSet(viewsets.ModelViewSet):
     lookup_field = 'id'
     permission_classes = [HasOrgRolePermission]
     http_method_names = ['get', 'patch']
-    renderer_classes = [
-        JSONRenderer,
-    ]
 
     @action(
         detail=True, methods=['GET'], permission_classes=[IsOrgAdminPermission]
@@ -385,9 +381,6 @@ class OrganizationMemberViewSet(viewsets.ModelViewSet):
     permission_classes = [OrganizationNestedHasOrgRolePermission]
     http_method_names = ['get', 'patch', 'delete']
     lookup_field = 'user__username'
-    renderer_classes = [
-        JSONRenderer,
-    ]
 
     def paginate_queryset(self, queryset):
         page = super().paginate_queryset(queryset)
@@ -604,7 +597,6 @@ class OrgMembershipInviteViewSet(viewsets.ModelViewSet):
     serializer_class = OrgMembershipInviteSerializer
     http_method_names = ['get', 'post', 'patch', 'delete']
     lookup_field = 'guid'
-    renderer_classes = (JSONRenderer,)
 
     def create(self, request, *args, **kwargs):
         serializer = self.get_serializer(data=request.data)

kobo/settings/base.py

@@ -992,7 +992,9 @@ def __init__(self, *args, **kwargs):
         'kpi.authentication.OAuth2Authentication',
     ],
     'DEFAULT_RENDERER_CLASSES': [
-       'rest_framework.renderers.JSONRenderer',
+        'rest_framework.renderers.JSONRenderer',
+        # "BasicHTMLRenderer" must always come after JSONRenderer
+        'kpi.renderers.BasicHTMLRenderer',
     ],
     'DEFAULT_VERSIONING_CLASS': 'kpi.versioning.APIAutoVersioning',
     # Cannot be placed in kpi.exceptions.py because of circular imports
@@ -1030,6 +1032,32 @@ def __init__(self, *args, **kwargs):
         'InviteStatusChoicesEnum': 'kobo.apps.organizations.models.OrganizationInviteStatusChoices.choices',  # noqa
         'InviteeRoleEnum': 'kpi.schema_extensions.v2.members.schema.ROLE_CHOICES_PAYLOAD_ENUM',  # noqa
     },
+    # We only want to blacklist BasicHTMLRenderer, but nothing like RENDERER_WHITELIST
+    # exists 🤦
+    # List all the renderers that are used by documented API
+    'RENDERER_WHITELIST': [
+        'rest_framework.renderers.JSONRenderer',
+        'rest_framework.renderers.StaticHTMLRenderer',
+        'kpi.renderers.MediaFileRenderer',
+        'kpi.renderers.MP3ConversionRenderer',
+        'kpi.renderers.OpenRosaRenderer',
+        'kpi.renderers.OpenRosaFormListRenderer',
+        'kpi.renderers.OpenRosaManifestRenderer',
+        'kpi.renderers.SSJsonRenderer',
+        'kpi.renderers.SubmissionGeoJsonRenderer',
+        'kpi.renderers.DoNothingRenderer',
+        'kpi.renderers.SubmissionXLSXRenderer',
+        'kpi.renderers.SubmissionCSVRenderer',
+        'kpi.renderers.SubmissionXMLRenderer',
+        'kpi.renderers.XMLRenderer',
+        'kpi.renderers.XFormRenderer',
+        'kpi.renderers.XlsRenderer',
+        'kobo.apps.openrosa.libs.renderers.renderers.XLSRenderer',
+        'kobo.apps.openrosa.libs.renderers.renderers.XLSXRenderer',
+        'kobo.apps.openrosa.libs.renderers.renderers.CSVRenderer',
+        'kobo.apps.openrosa.libs.renderers.renderers.RawXMLRenderer',
+        'kobo.apps.openrosa.libs.renderers.renderers.TemplateXMLRenderer'
+    ],
     'TAGS': [
         {
             'name': 'Manage projects and library content',

kpi/negotiation.py

@@ -7,14 +7,17 @@ class DefaultContentNegotiation(UpstreamDefaultContentNegociation):
 
     def select_renderer(self, request, renderers, format_suffix=None):
         """
-        Overrides the default DRF `select_renderer` to handle cases where the client
-        does not specify a compatible `Accept` header nor a format suffix.
+        Overrides DRF's `select_renderer` to customize content negotiation.
 
-        If the first available renderer is not included in the accepted media types
-        and no explicit format suffix is given, this override will forcibly return
-        the first renderer in the list.
+        - If the client request comes from a browser (i.e., the Accept header
+          includes `text/html`) and `BasicHTMLRenderer` is available, use it
+          as the renderer.
 
-        Otherwise, the default DRF negotiation logic is applied.
+        - If the first available renderer is not included in the accepted media
+          types and no explicit format suffix is provided, fall back to the
+          first renderer in the list.
+
+        - In all other cases, defer to DRF's default content negotiation logic.
         """
         format_query_param = self.settings.URL_FORMAT_OVERRIDE
         format_ = format_suffix or request.query_params.get(format_query_param)
@@ -23,9 +26,19 @@ def select_renderer(self, request, renderers, format_suffix=None):
         first_renderer = renderers[0]
         first_renderer_format_allowed = first_renderer.format in accepts
 
+        # Force HTML if the request comes from a browser
+        # (i.e., the Accept header includes HTML) and `BasicHTMLRenderer` is available
+        # in the list of renderers.
+        if (
+            'text/html' in accepts
+            and len(renderers) > 1
+            and renderers[1].__class__.__name__ == 'BasicHTMLRenderer'
+        ):
+            return renderers[1], renderers[1].media_type
+
+        # Force fallback to the first renderer
         if not first_renderer_format_allowed and not format_:
-            # force fallback to first renderer
             return first_renderer, first_renderer.media_type
 
-        # otherwise fallback to DRF's default content negotiation
+        # Otherwise fallback to DRF's default content negotiation
         return super().select_renderer(request, renderers, format_suffix)

kpi/renderers.py

@@ -4,18 +4,81 @@
 from collections.abc import Callable
 from io import StringIO
 
-import formpack
 from dict2xml import dict2xml
+from django.core.serializers.json import DjangoJSONEncoder
+from django.template.loader import get_template
 from django.utils.xmlutils import SimplerXMLGenerator
 from rest_framework import renderers, status
 from rest_framework.exceptions import ErrorDetail, ParseError
 from rest_framework_xml.renderers import XMLRenderer as DRFXMLRenderer
 
+import formpack
 from kobo.apps.reports.report_data import build_formpack
 from kpi.constants import GEO_QUESTION_TYPES
 from kpi.utils.xml import add_xml_declaration
 
 
+class BasicHTMLRenderer(renderers.BaseRenderer):
+    media_type = 'text/html'
+    format = 'html'
+    charset = 'utf-8'
+    template_name = 'renderers/basic.html'
+
+    PARAM_REGEXES = [
+        # (?P<uid>[^/.]+) -> {uid}
+        (re.compile(r'\(\?P<(?P<name>\w+)>(?:[^)]+)\)'), r'{\g<name>}'),
+        # <converter:name> or <name> -> {name}
+        (re.compile(r'<(?:\w+:)?(?P<name>\w+)>'), r'{\g<name>}'),
+    ]
+
+    def render(self, data, accepted_media_type=None, renderer_context=None):
+        request = renderer_context.get('request') if renderer_context else None
+        resolver_match = getattr(request, 'resolver_match', None)
+        url_pattern_clean = None
+
+        if resolver_match:
+            url_pattern_clean = self._clean_route(resolver_match.route)
+
+        try:
+            pretty = json.dumps(data, indent=2, cls=DjangoJSONEncoder)
+        except:
+            pretty = str(data)
+
+        context = {'pretty': pretty, 'q_param': url_pattern_clean or ''}
+
+        tpl = get_template(self.template_name)
+        return tpl.render(context)
+
+    @classmethod
+    def _clean_route(cls, raw: str | None) -> str | None:
+        if not raw:
+            return None
+        s = raw.strip()
+        # strip leading ^ and trailing $
+        s = s.lstrip('^').rstrip('$')
+        # Replace named groups and path converters by {name}
+        for rx, repl in cls.PARAM_REGEXES:
+            s = rx.sub(repl, s)
+        # Unescape slashes if a regex had them escaped
+        s = s.replace(r'\/', '/')
+        # Normalize multiple slashes (just in case)
+        s = re.sub(r'/{2,}', '/', s)
+
+        return s
+
+    @staticmethod
+    def _extract_raw_route(resolver) -> str | None:
+        """
+        Try to get the raw route/regex from ResolverMatch across Django versions.
+
+        """
+
+        if not resolver:
+            return None
+
+        return resolver.route
+
+
 class MediaFileRenderer(renderers.BaseRenderer):
 
     media_type = '*/*'

kpi/static/js/swagger/swagger-smart-search.js

@@ -2,6 +2,7 @@ window.onload = () => {
   const interval = setInterval(() => {
     const oldInput = document.querySelector('.operation-filter-input')
     const tags = document.querySelectorAll('.opblock-tag-section')
+    const params = new URLSearchParams(window.location.search)
     if (!oldInput || tags.length === 0) return
 
     clearInterval(interval)
@@ -10,35 +11,51 @@ window.onload = () => {
     oldInput.replaceWith(newInput)
     newInput.placeholder = 'Filter by tag, summary, or path'
 
+    const filter_query = params.get('q')
+    if (filter_query && filter_query.trim() !== '') {
+      newInput.value = filter_query
+      doSearch(filter_query.toLowerCase(), tags)
+    }
+
     newInput.addEventListener('input', () => {
       const query = newInput.value.toLowerCase()
+      doSearch(query, tags)
+    })
+  }, 200)
+}
+
+function doSearch(query, tags) {
+  // When tags are collapsed, their content is not in the DOM and we cannot search
+  // for keywords.
+  if (query !== '') {
+    expandAllTags()
+  } else {
+    collapseAllTags()
+  }
+
+  const endpointsInterval = setInterval(() => {
+    const endpoints = document.querySelectorAll('.opblock-tag')
+    if (endpoints.length === 0) return
 
-      // When tags are collapsed, their content is not in the DOM and we cannot search
-      // for keywords.
-      if (query !== '') {
-        expandAllTags()
-      } else {
-        collapseAllTags()
-      }
-
-      tags.forEach((tag) => {
-        let showTag = false
-        const operations = tag.querySelectorAll('.opblock')
-
-        operations.forEach((op) => {
-          const summary = op.querySelector('.opblock-summary-description')?.textContent.toLowerCase() || ''
-          const path = op.querySelector('.opblock-summary-path')?.textContent.toLowerCase() || ''
-          const tagName = tag.querySelector('.opblock-tag')?.textContent.toLowerCase() || ''
-          const match = summary.includes(query) || path.includes(query) || tagName.includes(query)
-
-          op.style.display = match ? '' : 'none'
-          if (match) showTag = true
-        })
-
-        tag.style.display = showTag ? '' : 'none'
+    clearInterval(endpointsInterval)
+
+    tags.forEach((tag) => {
+      let showTag = !query
+      const operations = tag.querySelectorAll('.opblock')
+
+      operations.forEach((op) => {
+        const summary = op.querySelector('.opblock-summary-description')?.textContent.toLowerCase() || ''
+        const path = op.querySelector('.opblock-summary-path')?.textContent.toLowerCase() || ''
+        const tagName = tag.querySelector('.opblock-tag')?.textContent.toLowerCase() || ''
+        const match = summary.includes(query) || path.includes(query) || tagName.includes(query)
+
+        op.style.display = match ? '' : 'none'
+        if (match) showTag = true
       })
+
+      tag.style.display = showTag ? '' : 'none'
     })
-  }, 200)
+  })
 }
 
 function expandAllTags() {

kpi/templates/renderers/basic.html

@@ -0,0 +1,17 @@
+{% extends "rest_framework/base.html" %}
+
+{% load static %}
+{% load i18n %}
+
+{% block navbar %}
+{% endblock %}
+
+{% block breadcrumbs %}
+{% endblock %}
+
+{% block content %}
+    <h1>KoboToolbox API</h1>
+    <p>For a general introduction to our API, please visit <a href="https://support.kobotoolbox.org/api.html">https://support.kobotoolbox.org/api.html</a>.</p>
+    <p>Detailed, developer-focused documentation can now be found on our <a href="{% url 'swagger-ui' %}?q={{ q_param }}">new API documentation pages</a>.</p>
+    <pre>{{ pretty }}</pre>
+{% endblock %}

kpi/urls/router_api_v2.py

@@ -14,6 +14,7 @@
 )
 from kobo.apps.project_ownership.urls import router as project_ownership_router
 from kobo.apps.project_views.views import ProjectViewViewSet
+from kpi.renderers import BasicHTMLRenderer
 from kpi.views.v2.asset import AssetViewSet
 from kpi.views.v2.asset_counts import AssetCountsViewSet
 from kpi.views.v2.asset_export_settings import AssetExportSettingsViewSet
@@ -211,17 +212,23 @@ def get_urls(self, *args, **kwargs):
 enketo_url_aliases = [
     path(
         'assets/<parent_lookup_asset>/data/<pk>/edit/',
-        DataViewSet.as_view({'get': 'enketo_edit'}, renderer_classes=[JSONRenderer]),
+        DataViewSet.as_view(
+            {'get': 'enketo_edit'}, renderer_classes=[JSONRenderer, BasicHTMLRenderer]
+        ),
         name='submission-enketo-edit-legacy',
     ),
     path(
         'assets/<parent_lookup_asset>/data/<pk>/enketo/redirect/edit/',
-        DataViewSet.as_view({'get': 'enketo_edit'}, renderer_classes=[JSONRenderer]),
+        DataViewSet.as_view(
+            {'get': 'enketo_edit'}, renderer_classes=[JSONRenderer]
+        ),
         name='submission-enketo-edit-redirect',
     ),
     path(
         'assets/<parent_lookup_asset>/data/<pk>/enketo/redirect/view/',
-        DataViewSet.as_view({'get': 'enketo_view'}, renderer_classes=[JSONRenderer]),
+        DataViewSet.as_view(
+            {'get': 'enketo_view'}, renderer_classes=[JSONRenderer]
+        ),
         name='submission-enketo-view-redirect',
     ),
 ]