django - 在 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

我是新手，但我发现您可以使用 aSimpleRouter而不是 aDefaultRouter来指定您自己的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
    """

ㄑ</p>

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

Answer 5

感谢frost-nzcr4上面的评论，我找到了一个很好的方法：

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

然后在你的urls.py：

router = MyRouter()

Answer 6

@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)
    })