In Django RestFramework, how to change the Api Root documentation?

Question

In django RestFramework, is there any "official" way to generate the documentation for the "Api Root" ?

After looking at the RestFramework's source code, I've found a work around by subclassing the DefaultRouter:

from rest_framework import routers

class MyRouter(routers.DefaultRouter):
    def get_api_root_view(self):
        api_root_view = super(MyRouter, self).get_api_root_view()
        ApiRootClass = api_root_view.cls

        class MyAPIRoot(ApiRootClass):
            """My API Root documentation"""
            pass

        return MyAPIRoot.as_view()

router = MyRouter()

Is there a cleaner or better way ?

paulhauner · Answer 1 · 2017-06-01T00:20:50.440

22

I found a solution through experimentation.

I prefer it to the other solutions in this thread as it requires less code and allows you to customise the API title, as well as the documentation for the API root.

from rest_framework import routers

class ThisWillBeTheApiTitleView(routers.APIRootView):
    """
    This appears where the docstring goes!
    """
    pass


class DocumentedRouter(routers.DefaultRouter):
    APIRootView = ThisWillBeTheApiTitleView


router = DocumentedRouter()
router.register(r'items', ItemsViewSet)

This renders as below:

edited Jun 01 '17 at 00:20

answered May 30 '17 at 12:46

paulhauner

1,434
13
15

3

I've you dive a bit deeper to bring you the knowledge of these settings: - VIEW_NAME_FUNCTION = 'rest_framework.views.get_view_name' - VIEW_DESCRIPTION_FUNCTION = 'rest_framework.views.get_view_description' So your class just need to define it's *name* and *description* property to render what you need. – frost-nzcr4 Sep 19 '19 at 19:16

score 15 · Answer 2 · answered Jun 21 '18 at 04:21

15

If anyone wants an inline style

   router = DefaultRouter()

   router.get_api_root_view().cls.__name__ = "Root API name"
   router.get_api_root_view().cls.__doc__ = "Your Description"

answered Jun 21 '18 at 04:21

digitake

846
7
16

Be careful. This will set the name of the APIRootView itself, which will apply to all DefaultRouters in the system. – Diego Aragão Aug 23 '22 at 13:46

score 14 · Accepted Answer · edited Jan 22 '14 at 22:40

14

I'm new to this but I found you can use a SimpleRouter instead of a DefaultRouter to specify your own APIRoot.

in urls.py in your api module

from django.conf.urls import patterns, url, include
from rest_framework.routers import SimpleRouter
router = SimpleRouter()

urlpatterns = patterns('api.views',
    url(r'^$', views.APIRoot.as_view()),
    url(r'', include(router.urls)),
)

Then specify the documentation in the class comment

from rest_framework import generics

class APIRoot(generics.GenericAPIView):
    """
    My API documentation
    """

ㄑ

edited Jan 22 '14 at 22:40

Daniel Naab

22,690
8
54
55

answered Sep 11 '13 at 02:34

Shih-Wen Su

2,589
24
21

with your approach, using `SimpleRouter` or `DefaultRouter` doesn't really matter. You can still use `DefaultRouter` without any problem. Especially if you need the [**format suffix**](http://www.django-rest-framework.org/api-guide/routers/#defaultrouter) provided from it. – Yeo Oct 02 '16 at 12:41
What would be the best way to do the same thing, but not break anything else? I mean this completly overwrites the normal API root view, so things might stop working. – Joakim Feb 17 '17 at 15:37

Régis B. · Answer 4 · 2016-09-14T09:32:19.127

5

It's kind of difficult to override the APIRoot class. The most simple way to achieve what you want is probably to modify the __doc__ attribute of the APIRootClass at runtime in your urls.py:

class Router(routers.DefaultRouter):
    def get_api_root_view(self, api_urls=None):
        root_view = super(Router, self).get_api_root_view(api_urls=api_urls)
        root_view.cls.__doc__ = "Place your documentation here"
        return root_view

router = Router()
router.register(...)

urlpatterns = [
    url(r'^', include(router.urls)),
]

edited Sep 14 '16 at 09:32

answered Sep 14 '16 at 08:02

Régis B.

10,092
6
54
90

In Python 2 you get an exception trying to write `__doc__` – Joakim Feb 17 '17 at 15:36

Jason McVetta · Answer 5 · 2019-11-21T05:17:46.903

Thanks to frost-nzcr4's comment above, I found a nice way to do this:


from rest_framework import routers
from django.utils.safestring import mark_safe


class MyAPIRootView(routers.APIRootView):
    """
    Controls appearance of the API root view
    """

    def get_view_name(self) -> str:
        return "My API"

    def get_view_description(self, html=False) -> str:
        text = "My REST API"
        if html:
            return mark_safe(f"<p>{text}</p>")
        else:
            return text


class MyRouter(routers.DefaultRouter):
    APIRootView = MyAPIRootView

Then use this router in your urls.py:

router = MyRouter()

score 1 · Answer 6 · answered Mar 20 '18 at 20:45

1

@api_view(['GET'])
def api_root(request, format=None):
    return Response({
        'users': reverse('user-list', request=request, format=format),
        'snippets': reverse('snippet-list', request=request, format=format)
    })

answered Mar 20 '18 at 20:45

BDA

11
1

In Django RestFramework, how to change the Api Root documentation?

6 Answers6

Linked