如何在DRF文档

Question

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

基本上，我跟随the official documentation并在我的网址集配置中使用此功能：

from rest_framework.documentation import include_docs_urls

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

一切似乎都有效，我得到了一个很好的交互式文档页面，但我有一个ViewSet lookup_field = "slug"，关于生成的文档的一件事困扰着我：

我希望获得一些有用的信息，例如＆＃34;一个独特的永久分配的字母数字ID＆＃34;或者这些内容中的某些内容，但无法找到此数据来源的任何文档。

有一种解决方法，但我真的不想define all the schema explicitly。我想用很好的文档字符串声明我的类，并自动生成文档。我还发现了将slug -- here goes the description放入文档字符串的建议，但它似乎不起作用 - 文本只显示Markdown格式化描述的其余部分。

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

1. （具体问题）我在哪里填写此路径参数说明？
2. （同一问题的更通用版本）了解如何从代码自动生成模式的最佳方法是什么？

Answer 1

哦，我找到了。回答我自己的问题。

DRF文档在这件事上并不详细（或者我错过了它的作品），但它提到了rest_framework.schemas.SchemaGenerator class并且看起来这个类真的做了所有内省的东西。幸运的是，源代码结构合理，易于阅读。

这些路径字段是由get_path_fields方法生成的（我通过跟踪执行路径找到它：get_schema→get_links→get_link），我发现了这些描述{ {3}}属性。

所以在我的模型中我指定了：

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

它有效！

Answer 2

还有一件重要的事情还没有涵盖。确实，描述来自help_text属性，但这还不够。我发现模式生成器依赖view's queryset属性来确定模型。所以，请记住，即使您不需要，也需要定义它。例如，在使用APIView的情况下。