如何在DRF文档中描述参数

Question

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

基本上，我遵循官方文档并在我的URL配置中使用它：

from rest_framework.documentation import include_docs_urls

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

一切似乎都运行良好，我得到了一个漂亮的交互式文档页面，但我有一个ViewSet，其中lookup_field =“slug”，有关生成的文档中有一件事情让我困扰：

我想在那个描述中提供一些有用的信息，比如“唯一永久指定的字母数字 ID”之类的东西，但是找不到任何文档说明这些数据来自何处。

有一个解决办法，但我真的不想显式定义所有模式。我希望声明我的类有良好的docstrings并自动生成文档。我还发现了一个建议，在docstring中放置slug-在此处输入说明，但它似乎不起作用-该文本只是以其余的Markdown格式化的说明一起出现。

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

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

- drdaeman

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"))
    ...

它起作用了！

- drdaeman

---

这对我来说有一半的作用。它对对象主键没有影响。看了你提供的链接，它应该根据使用的主键类型（在我的情况下是UUID）自动解析出描述。可惜它只是显示为空白。 - freethebees

Answer 2

还有一件重要的事情尚未涉及。的确，描述信息来自于help_text属性，但这并不足够。我发现模式生成器依赖于视图的queryset属性来确定一个模型。所以，请记住，即使您不需要它，在使用APIView时也需要定义它。

- dismine