在Django RestFramework中,如何更改Api Root文档？

Question

在django RestFramework中,是否有任何"官方"方式来生成"Api Root"的文档？

在查看RestFramework的源代码之后,我通过继承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()

有更干净或更好的方式吗？

Answer 1

我通过实验找到了解决方案.

我更喜欢这个线程中的其他解决方案,因为它需要更少的代码,并允许您自定义API标题,以及API根目录的文档.

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)

这呈现如下:

Answer 2

如果有人想要内联样式

   router = DefaultRouter()

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

Answer 3

我是新手,但我发现你可以使用a SimpleRouter代替a DefaultRouter来指定你自己的APIRoot.

在urls.py您的API模块

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)),
)

然后在类注释中指定文档

from rest_framework import generics

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

ㄑ

Answer 4

重写 APIRoot 类有点困难。实现您想要的最简单方法可能是__doc__在运行时修改APIRootClass的属性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)),
]