如何在DRF文档中描述参数 [英] How to describe parameters in DRF Docs

问题描述

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

基本上，我正在关注

我想获取一些有用的信息，例如唯一的永久分配的字母数字ID或其中的某些内容，但找不到此数据的来源。

有一种解决方法，但我真的不想明确定义所有模式。我想用漂亮的文档字符串声明我的类并自动生成的文档。我还发现了一个建议，将 slug-此处的描述放在文档字符串中，但似乎不起作用-文本仅显示为

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

1. （一个特定的问题）在哪里填写此路径参数说明？


2. （同一问题的更多通用版本）学习模式的最佳方法是什么是从代码自动生成的？

解决方案

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

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 = _（唯一的字母数字标识符 ））
 ... 
  

而且有效！

I'm using Django REST Framework v3.6 built-in interactive documentation django_rest_framework.documentation (not django-rest-swagger).

Basically, I'm following the official documentation and use this in my URLset configuration:

from rest_framework.documentation import include_docs_urls

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

Everything seems to work and I get a nice interactive documentation page, but I have a ViewSet with lookup_field = "slug" and one thing about the generated documentation bothers me:

I want to have some useful information it that description, like "an unique permanently-assigned alphanumeric ID" or something among those lines, but can't find any documentation where this data comes from.

There is a workaround but I really don't want to define all the schema explicitly. I want to declare my classes with nice docstrings and have docs auto-generated. I've also found an suggestion to put slug -- here goes the description in the docstring but it doesn't seem work - the text just appears with the rest of the Markdown-formatted description.

So... I wonder about two things:

1. (A specific question) Where do I fill this path parameter description?
2. (More generic version of the same question) What's the best way to learn how schemas are auto-generated from code?

解决方案

Oh, I found it. Answering my own question.

DRF documentation isn't verbose on this matter (or I've missed the piece where it is), but it mentions rest_framework.schemas.SchemaGenerator class and it seems that this class really does all the introspection stuff. Fortunately, the source code is well-structured and easy to read.

Those path fields are generated by get_path_fields method (I found it by tracing the execution path: get_schema → get_links → get_link), and I found that descriptions come from model fields's help_text attribute.

So in my model I've specified:

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

And it worked!

这篇关于如何在DRF文档中描述参数的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！