如何从API文档中排除视图？

I use django-rest-framework (DRF) to provide the REST API of a site of mine. From what I understand, the automatic generation of API documentation relies on DRF's generation of a schema. It may then be interpreted by a third-party tool to produce pretty documentation. I've used django-rest-swagger as the tool that produces the pretty documentation from DRF's schema, but I suspect the solution to my problem is DRF-based, independent of whatever tool I use to transform the schema to something "pretty".

我使用django-rest-framework(DRF)来提供我的站点的REST API。据我所知,API文档的自动生成依赖于DRF生成的模式。然后可以由第三方工具解释它以生成漂亮的文档。我使用django-rest-swagger作为从DRF模式生成漂亮文档的工具,但我怀疑我的问题的解决方案是基于DRF的,独立于我用来将模式转换为“漂亮”的任何工具。

The problem is that by default, DRF provides documentation for the whole API, even though some parts of it are really for my sites own internal purpose. I'd like some views to be excluded from the documentation. Some views should always be excluded. Some views should be excluded only if the user viewing the documentation is not logged into the site.

问题是默认情况下,DRF提供整个API的文档,即使它的某些部分确实是我的网站自己的内部目的。我希望从文档中排除一些观点。应始终排除某些观点。仅当查看文档的用户未登录到站点时,才应排除某些视图。

1 个解决方案

#1

This isn't well documented. On a class-based view, you can set the exclude_from_schema attribute to True to exclude the view from the documentation. Example:

这没有很好的记录。在基于类的视图上,您​​可以将exclude_from_schema属性设置为True以从文档中排除视图。例:

from rest_framework import viewsets, mixins
class SomeViewSet(mixins...., viewsets.GenericViewSet):
    exclude_from_schema = True

    [...]

If you search the current documentation for exclude_from_schema you'll find a hit here, which documents the presence of a parameter for the @api_view decorator, which has for effect of setting the attribute as shown above. The attribute itself though is currently not mentioned in DRF's documentation.

如果你在当前文档中搜索exclude_from_schema,你会在这里找到一个命中,它记录了@api_view装饰器的参数的存在,这有助于设置如上所示的属性。虽然DRF的文档中没有提到属性本身。

If you want to exclude a view based on a condition, you can use the @property decorator so that exclude_from_schema becomes a computed attribute. Behind the scenes, when DRF needs to produce the schema for the view, it will instantiate the class with the Request object that was generated when the user browsed to the documentation page. So you can test to check whether the user that is accessing the documentation was authenticated or not:

如果要根据条件排除视图,可以使用@property装饰器,以使exclude_from_schema成为计算属性。在幕后,当DRF需要为视图生成模式时,它将使用在用户浏览到文档页面时生成的Request对象来实例化该类。因此,您可以进行测试以检查访问文档的用户是否已经过身份验证:

from rest_framework import viewsets, mixins, permissions
class SomeViewSet(mixins...., viewsets.GenericViewSet):
    @property
    def exclude_from_schema(self):
        return not permissions.IsAuthenticated().has_permission(self.request,
                                                                self)

    [...]

self.request is the Request object that was generated when the user asked for the documentation. We use one of the classes provided by rest_framework.permissions directly because the code that generates the schema does not use the permission_classes attribute that may be set on SomeViewSet.

self.request是用户要求提供文档时生成的Request对象。我们直接使用rest_framework.permissions提供的类之一,因为生成模式的代码不使用可能在SomeViewSet上设置的permission_classes属性。