44

如果我有这样的看法：

class MyAPIView(APIView):
    def get(self, request, name=None):
        return {"hello": name or "world"}

如何将其包含在生成的文档中？具体来说，如何将它包含在 API Root 中，以便在我访问“ http://example.com/api/ ”时出现？

该文档包括一个带有描述的 APIView 示例，但没有描述实际将其包含在 API 浏览器中的过程。

4

6 回答 6

32

为了与路由器和 APIView 类或方法混合，以使 API Root 在 APIRoot 视图中以最少的代码视图显示两者，我编写了一个自定义路由器，它扩展了 DefaultRouter 并覆盖了 get_urls 和 get_api_root_view；它看起来如下：

from rest_framework import routers, views, reverse, response

class HybridRouter(routers.DefaultRouter):
    def __init__(self, *args, **kwargs):
        super(HybridRouter, self).__init__(*args, **kwargs)
        self._api_view_urls = {}

    def add_api_view(self, name, url):
        self._api_view_urls[name] = url

    def remove_api_view(self, name):
        del self._api_view_urls[name]

    @property
    def api_view_urls(self):
        ret = {}
        ret.update(self._api_view_urls)
        return ret

    def get_urls(self):
        urls = super(HybridRouter, self).get_urls()
        for api_view_key in self._api_view_urls.keys():
            urls.append(self._api_view_urls[api_view_key])
        return urls

    def get_api_root_view(self):
        # Copy the following block from Default Router
        api_root_dict = {}
        list_name = self.routes[0].name
        for prefix, viewset, basename in self.registry:
            api_root_dict[prefix] = list_name.format(basename=basename)
        api_view_urls = self._api_view_urls

        class APIRoot(views.APIView):
            _ignore_model_permissions = True

            def get(self, request, format=None):
                ret = {}
                for key, url_name in api_root_dict.items():
                    ret[key] = reverse.reverse(url_name, request=request, format=format)
                # In addition to what had been added, now add the APIView urls
                for api_view_key in api_view_urls.keys():
                    ret[api_view_key] = reverse.reverse(api_view_urls[api_view_key].name, request=request, format=format)
                return response.Response(ret)

        return APIRoot.as_view()

然后我用它作为 -

router = routers.HybridRouter()
router.register(r'abc', views.ABCViewSet)
router.add_api_view("api-view", url(r'^aview/$', views.AView.as_view(), name='aview-name'))
urlpatterns = patterns('',
    url(r'^api/', include(router.urls)),
于 2014-04-27T09:09:48.230 回答
20

生成的文档？

嗨大卫，首先我不会将可浏览的API描述为“生成的文档”。

如果您需要静态文档，最好查看第三方工具，例如django-rest-swagger。

可浏览的 API 确实意味着您构建的 API 将是自描述的，但它与传统的静态文档工具略有不同。可浏览的 API 确保您在 API 中创建的所有端点都能够以机器可读（即 JSON）和人类可读（即 HTML）表示形式进行响应。它还确保您可以直接通过浏览器进行完全交互——您通常使用编程客户端与之交互的任何 URL 也将能够以浏览器友好视图响应 API。

我怎样才能把它包括在内。

只需向视图添加一个文档字符串，它将包含在您路由到该视图的任何 URL 的可浏览 API 表示中。

默认情况下，您可以使用 markdown 表示法在描述中包含 HTML 标记，但您也可以自定义该行为，例如，如果您更愿意使用 rst。

具体来说，我怎样才能将它包含在 API Root 中。

您只需将 URL 显式添加到您连接到的任何视图返回的响应中/api/。例如...

from rest_framework import renderers
from rest_framework.views import APIView
from rest_framework.response import Response
from rest_framework.reverse import reverse


class APIRoot(APIView):
    def get(self, request):
        # Assuming we have views named 'foo-view' and 'bar-view'
        # in our project's URLconf.
        return Response({
            'foo': reverse('foo-view', request=request),
            'bar': reverse('bar-view', request=request)
        })
于 2013-09-16T08:26:34.857 回答
4

我为我的用例优化了 HybridRouter 并删除了一些代码。一探究竟：

class HybridRouter(routers.DefaultRouter):
    def __init__(self, *args, **kwargs):
        super(HybridRouter, self).__init__(*args, **kwargs)
        self.view_urls = []

    def add_url(self, view):
        self.view_urls.append(view)

    def get_urls(self):
        return super(HybridRouter, self).get_urls() + self.view_urls

    def get_api_root_view(self):
        original_view = super(HybridRouter, self).get_api_root_view()

        def view(request, *args, **kwargs):
            resp = original_view(request, *args, **kwargs)
            namespace = request.resolver_match.namespace
            for view_url in self.view_urls:
                name = view_url.name
                url_name = name
                if namespace:
                    url_name = namespace + ':' + url_name
                resp.data[name] = reverse(url_name,
                                          args=args,
                                          kwargs=kwargs,
                                          request=request,
                                          format=kwargs.get('format', None))
            return resp
        return view

和用法：

router = routers.HybridRouter(trailing_slash=False)
router.add_url(url(r'^me', v1.me.view, name='me'))
router.add_url(url(r'^status', v1.status.view, name='status'))

urlpatterns = router.urls

或者：

router = routers.HybridRouter(trailing_slash=False)
router.view_urls = [
    url(r'^me', v1.me.view, name='me'),
    url(r'^status', v1.status.view, name='status'),
]

urlpatterns = router.urls
于 2016-05-23T10:15:12.097 回答
3

作为记录，现在是 2019 年，https://bitbucket.org/hub9/django-hybrid-router仍在工作，唯一的修改是必须将第 64 行编辑为：

                regex = api_view_urls[api_view_key].pattern.regex
于 2019-02-04T16:10:46.247 回答
3

@imyousuf 代码的更新版本可与 DRF 3.4.1 一起使用。

class HybridRouter(routers.DefaultRouter):
    def __init__(self, *args, **kwargs):
        super(HybridRouter, self).__init__(*args, **kwargs)
        self._api_view_urls = {}

    def add_api_view(self, name, url):
        self._api_view_urls[name] = url

    def remove_api_view(self, name):
        del self._api_view_urls[name]

    @property
    def api_view_urls(self):
        ret = {}
        ret.update(self._api_view_urls)
        return ret

    def get_urls(self):
        urls = super(HybridRouter, self).get_urls()
        for api_view_key in self._api_view_urls.keys():
            urls.append(self._api_view_urls[api_view_key])
        return urls

    def get_api_root_view(self, api_urls=None):
        # Copy the following block from Default Router
        api_root_dict = OrderedDict()
        list_name = self.routes[0].name
        for prefix, viewset, basename in self.registry:
            api_root_dict[prefix] = list_name.format(basename=basename)

        view_renderers = list(self.root_renderers)
        schema_media_types = []

        if api_urls and self.schema_title:
            view_renderers += list(self.schema_renderers)
            schema_generator = SchemaGenerator(
                title=self.schema_title,
                url=self.schema_url,
                patterns=api_urls
            )
            schema_media_types = [
                renderer.media_type
                for renderer in self.schema_renderers
                ]

        api_view_urls = self._api_view_urls

        class APIRoot(views.APIView):
            _ignore_model_permissions = True
            renderer_classes = view_renderers

            def get(self, request, *args, **kwargs):
                if request.accepted_renderer.media_type in schema_media_types:
                    # Return a schema response.
                    schema = schema_generator.get_schema(request)
                    if schema is None:
                        raise exceptions.PermissionDenied()
                    return Response(schema)

                # Return a plain {"name": "hyperlink"} response.
                ret = OrderedDict()
                namespace = request.resolver_match.namespace
                for key, url_name in api_root_dict.items():
                    if namespace:
                        url_name = namespace + ':' + url_name
                    try:
                        ret[key] = reverse.reverse(
                            url_name,
                            args=args,
                            kwargs=kwargs,
                            request=request,
                            format=kwargs.get('format', None)
                        )
                    except NoReverseMatch:
                        # Don't bail out if eg. no list routes exist, only detail routes.
                        continue

                # In addition to what had been added, now add the APIView urls
                for api_view_key in api_view_urls.keys():
                    url_name = api_view_urls[api_view_key].name
                    if namespace:
                        url_name = namespace + ':' + url_name
                    ret[api_view_key] = reverse.reverse(url_name, request=request, format=kwargs.get('format'))

                return response.Response(ret)

        return APIRoot.as_view()

如何使用：

mobile_router = HybridRouter()
mobile_router.add_api_view("device", url(r'^device/register/$', DeviceViewSet.as_view({'post': 'register'}), name='device-register'))
于 2016-07-29T14:29:08.840 回答
1

@imyousuf 的解决方案很好，但它不支持 url 命名空间并且有点过时。

这是它的更新：

class HybridRouter(routers.DefaultRouter):
    def __init__(self, *args, **kwargs):
        super(HybridRouter, self).__init__(*args, **kwargs)
        self._api_view_urls = {}

    def add_api_view(self, name, url):
        self._api_view_urls[name] = url

    def remove_api_view(self, name):
        del self._api_view_urls[name]

    @property
    def api_view_urls(self):
        ret = {}
        ret.update(self._api_view_urls)
        return ret

    def get_urls(self):
        urls = super(HybridRouter, self).get_urls()
        for api_view_key in self._api_view_urls.keys():
            urls.append(self._api_view_urls[api_view_key])
        return urls

    def get_api_root_view(self):

        # Copy the following block from Default Router
        api_root_dict = {}
        list_name = self.routes[0].name
        for prefix, viewset, basename in self.registry:
            api_root_dict[prefix] = list_name.format(basename=basename)

        # In addition to that:
        api_view_urls = self._api_view_urls

        class APIRoot(views.APIView):
            _ignore_model_permissions = True

            def get(self, request, *args, **kwargs):
                ret = OrderedDict()
                namespace = request.resolver_match.namespace
                for key, url_name in api_root_dict.items():
                    if namespace:
                        url_name = namespace + ':' + url_name
                    try:
                        ret[key] = reverse(
                            url_name,
                            args=args,
                            kwargs=kwargs,
                            request=request,
                            format=kwargs.get('format', None)
                        )
                    except NoReverseMatch:
                        # Don't bail out if eg. no list routes exist, only detail routes.
                        continue

                # In addition to what had been added, now add the APIView urls
                for api_view_key in api_view_urls.keys():
                    namespace = request.resolver_match.namespace
                    if namespace:
                        url_name = namespace + ":" + api_view_key
                    ret[api_view_key] = reverse(url_name,
                                        args=args,
                                        kwargs=kwargs,
                                        request=request,
                                        format=kwargs.get('format', None))

                return response.Response(ret)

        return APIRoot.as_view()
于 2016-03-03T09:44:44.827 回答