Enhance api_endpoint model to track the tree structure of an api, and add router settings for a better integration of viewsets.

Author: dimitri-justeau

rest_framework_docs/api_docs.py

@@ -1,16 +1,23 @@
 from importlib import import_module
+from types import ModuleType
 from django.conf import settings
 from django.core.urlresolvers import RegexURLResolver, RegexURLPattern
 from django.utils.module_loading import import_string
 from rest_framework.views import APIView
-from rest_framework_docs.api_endpoint import ApiEndpoint
+from rest_framework.routers import BaseRouter
+from rest_framework_docs.api_endpoint import ApiNode, ApiEndpoint
+from rest_framework_docs.settings import DRFSettings
+
+
+drf_settings = DRFSettings().settings
 
 
 class ApiDocumentation(object):
 
     def __init__(self, drf_router=None):
         self.endpoints = []
         self.drf_router = drf_router
+
         try:
             root_urlconf = import_string(settings.ROOT_URLCONF)
         except ImportError:
@@ -21,26 +28,113 @@ def __init__(self, drf_router=None):
         else:
             self.get_all_view_names(root_urlconf.urlpatterns)
 
-    def get_all_view_names(self, urlpatterns, parent_pattern=None):
+    def get_all_view_names(self, urlpatterns, parent_api_node=None):
         for pattern in urlpatterns:
             if isinstance(pattern, RegexURLResolver):
-                parent_pattern = None if pattern._regex == "^" else pattern
-                self.get_all_view_names(urlpatterns=pattern.url_patterns, parent_pattern=parent_pattern)
-            elif isinstance(pattern, RegexURLPattern) and self._is_drf_view(pattern) and not self._is_format_endpoint(pattern):
-                api_endpoint = ApiEndpoint(pattern, parent_pattern, self.drf_router)
+                # Try to get router from settings, if no router is found,
+                # Use the instance drf_router property.
+                router = get_router(pattern)
+                if router is None:
+                    parent_router = None
+                    if parent_api_node is not None:
+                        parent_router = parent_api_node.drf_router
+                    if parent_router is not None:
+                        router = parent_router
+                    else:
+                        router = self.drf_router
+                if pattern._regex == "^":
+                    parent = parent_api_node
+                else:
+                    parent = ApiNode(
+                        pattern,
+                        parent_node=parent_api_node,
+                        drf_router=router
+                    )
+                self.get_all_view_names(urlpatterns=pattern.url_patterns, parent_api_node=parent)
+            elif isinstance(pattern, RegexURLPattern) and _is_drf_view(pattern) and not _is_format_endpoint(pattern):
+                router = parent_api_node.drf_router
+                router = self.drf_router if router is None else router
+                api_endpoint = ApiEndpoint(pattern, parent_api_node, router)
                 self.endpoints.append(api_endpoint)
 
-    def _is_drf_view(self, pattern):
-        """
-        Should check whether a pattern inherits from DRF's APIView
-        """
-        return hasattr(pattern.callback, 'cls') and issubclass(pattern.callback.cls, APIView)
+    def get_endpoints(self):
+        return self.endpoints
 
-    def _is_format_endpoint(self, pattern):
-        """
-        Exclude endpoints with a "format" parameter
+
+def _is_drf_view(pattern):
+    """
+    Should check whether a pattern inherits from DRF's APIView
+    """
+    return hasattr(pattern.callback, 'cls') and issubclass(pattern.callback.cls,
+                                                           APIView)
+
+
+def _is_format_endpoint(pattern):
+    """
+    Exclude endpoints with a "format" parameter
+    """
+    return '?P<format>' in pattern._regex
+
+
+def get_router(pattern):
+    urlconf = pattern.urlconf_name
+    router = None
+    if isinstance(urlconf, ModuleType):
+        # First: try MODULE_ROUTERS setting - Don't ignore errors
+        router = get_module_router(urlconf)
+        if router is not None:
+            return router
+        # Second: try DEFAULT_MODULE_ROUTER setting - Ignore errors
+        try:
+            router = get_default_module_router(urlconf)
+            if router is not None:
+                return router
+        except:
+            pass
+        # Third: try DEFAULT_ROUTER setting - Don't ignore errors
+        router = get_default_router()
+        if router is not None:
+            return router
+    return router
+
+
+def get_module_router(module):
+    routers = drf_settings['MODULE_ROUTERS']
+    if routers is None:
+        return None
+    if module.__name__ in routers:
+        router_name = routers[module.__name__]
+        router = getattr(module, router_name)
+        assert isinstance(router, BaseRouter), \
+            """
+            drfdocs 'ROUTERS' setting does not correspond to
+            a router instance for module {}.
+            """.format(module.__name__)
+        return router
+    return None
+
+
+def get_default_module_router(module):
+    default_module_router = drf_settings['DEFAULT_MODULE_ROUTER']
+    if default_module_router is None:
+        return None
+    router = getattr(module, default_module_router)
+    assert isinstance(router, BaseRouter), \
         """
-        return '?P<format>' in pattern._regex
+        drfdocs 'DEFAULT_MODULE_ROUTER' setting does not correspond to
+        a router instance for module {}.
+        """.format(module.__name__)
+    return router
 
-    def get_endpoints(self):
-        return self.endpoints
+
+def get_default_router():
+    default_router_path = drf_settings['DEFAULT_ROUTER']
+    if default_router_path is None:
+        return None
+    router = import_string(default_router_path)
+    assert isinstance(router, BaseRouter), \
+        """
+        drfdocs 'DEFAULT_ROUTER_NAME' setting does not correspond to
+        a router instance {}.
+        """.format(router.__name__)
+    return router

rest_framework_docs/api_endpoint.py

@@ -5,18 +5,73 @@
 from rest_framework.serializers import BaseSerializer
 
 
-class ApiEndpoint(object):
+class ApiNode(object):
 
-    def __init__(self, pattern, parent_pattern=None, drf_router=None):
-        self.drf_router = drf_router
+    def __init__(self, pattern, parent_node=None, drf_router=None):
         self.pattern = pattern
+        self.parent_node = parent_node
+        self.drf_router = drf_router
+
+    @property
+    def parent_pattern(self):
+        if self.parent_node is None:
+            return None
+        return self.parent_node.pattern
+
+    @property
+    def name_parent(self):
+        if self.parent_pattern is None:
+            return None
+        return simplify_regex(self.parent_pattern.regex.pattern).strip('/')
+
+    @property
+    def name_parent_full(self):
+        name_parent_full = self.name_parent
+        if name_parent_full is None:
+            return None
+        parent_node = self.parent_node
+        parent_name = parent_node.name_parent
+        while parent_name is not None:
+            name_parent_full = "{}/{}".format(parent_name, name_parent_full)
+            parent_node = parent_node.parent_node
+            parent_name = parent_node.name_parent
+        return name_parent_full
+
+    @property
+    def path(self):
+        pattern = self.__get_path__(self.parent_pattern)
+        if pattern is None:
+            return None
+        parent = self.parent_node
+        name_parent = None if parent is None else parent.name_parent
+        while name_parent is not None:
+            pattern = "{}/{}".format(name_parent, pattern)
+            parent = parent.parent_node
+            name_parent = parent.name_parent
+        if pattern[0] != "/":
+            pattern = "/{}".format(pattern)
+        return pattern
+
+    def __get_path__(self, parent_pattern):
+        if parent_pattern:
+            return "{0}{1}".format(
+                self.name_parent,
+                simplify_regex(self.pattern.regex.pattern)
+            )
+        return simplify_regex(self.pattern.regex.pattern)
+
+
+class ApiEndpoint(ApiNode):
+
+    def __init__(self, pattern, parent_node=None, drf_router=None):
+        super(ApiEndpoint, self).__init__(
+            pattern,
+            parent_node=parent_node,
+            drf_router=drf_router
+        )
         self.callback = pattern.callback
-        # self.name = pattern.name
         self.docstring = self.__get_docstring__()
-        self.name_parent = simplify_regex(parent_pattern.regex.pattern).strip('/') if parent_pattern else None
-        self.path = self.__get_path__(parent_pattern)
         self.allowed_methods = self.__get_allowed_methods__()
-        # self.view_name = pattern.callback.__name__
         self.errors = None
         self.serializer_class = self.__get_serializer_class__()
         if self.serializer_class:
@@ -26,13 +81,7 @@ def __init__(self, pattern, parent_pattern=None, drf_router=None):
 
         self.permissions = self.__get_permissions_class__()
 
-    def __get_path__(self, parent_pattern):
-        if parent_pattern:
-            return "/{0}{1}".format(self.name_parent, simplify_regex(self.pattern.regex.pattern))
-        return simplify_regex(self.pattern.regex.pattern)
-
     def __get_allowed_methods__(self):
-
         viewset_methods = []
         if self.drf_router:
             for prefix, viewset, basename in self.drf_router.registry:

rest_framework_docs/settings.py

@@ -5,7 +5,10 @@ class DRFSettings(object):
 
     def __init__(self):
         self.drf_settings = {
-            "HIDE_DOCS": self.get_setting("HIDE_DOCS") or False
+            "HIDE_DOCS": self.get_setting("HIDE_DOCS") or False,
+            "MODULE_ROUTERS": self.get_setting("MODULE_ROUTERS"),
+            "DEFAULT_MODULE_ROUTER": self.get_setting("DEFAULT_MODULE_ROUTER"),
+            "DEFAULT_ROUTER": self.get_setting("DEFAULT_ROUTER")
         }
 
     def get_setting(self, name):

rest_framework_docs/templates/rest_framework_docs/home.html

@@ -15,7 +15,7 @@
 
 {% block content %}
 
-  {% regroup endpoints by name_parent as endpoints_grouped %}
+  {% regroup endpoints by name_parent_full as endpoints_grouped %}
 
   {% if endpoints_grouped %}
   {% for group in endpoints_grouped %}