如何在DRF文档中描述参数

Question

我正在使用Django REST Framework v3.6内置交互式文档django_rest_framework.documentation(不是 django-rest-swagger).

基本上,我正在遵循官方文档并在我的URLset配置中使用它:

from rest_framework.documentation import include_docs_urls

urlpatterns = [
    url(r"^", include_docs_urls(title="My API")),
    ...
]

一切似乎工作,我得到一个不错的交互式文档页面,但我有一个ViewSet与lookup_field = "slug"一两件事有关生成的文档困扰着我:

我希望获得一些有用的信息,例如"一个独特的永久分配的字母数字ID"或这些行之类的东西,但找不到这些数据来自的任何文档.

有一种解决方法,但我真的不想明确定义所有架构.我想用很好的文档字符串声明我的类,并自动生成文档.我还发现了一个建议放入slug -- here goes the description文档字符串,但它似乎不起作用 - 文本只显示Markdown格式描述的其余部分.

所以......我想知道两件事:

Answer 1

哦,我找到了.回答我自己的问题.

DRF文档在这个问题上并不详细(或者我错过了它所在的部分),但它提到了rest_framework.schemas.SchemaGenerator类,看起来这个类真的做了所有内省的东西.幸运的是,源代码结构良好且易于阅读.

那些路径字段由生成get_path_fields方法(我发现它通过跟踪执行路径:get_schema→交通get_links→交通get_link),我发现,描述来自模型字段的help_text属性.

所以在我的模型中我已经指定:

class MyResource(models.Model):
    slug = models.CharField(unique=True, help_text=_("unique alphanumeric identifier"))
    ...

它奏效了!

Answer 2

一件重要的事情还没有被涵盖。确实，描述来自help_text属性，但这还不够。我发现模式生成器依赖于视图的queryset属性来确定模型。因此，请记住，即使您不需要它，也需要定义它。例如在使用APIView.