How to describe parameters in DRF Docs

问题:

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?

回答1:

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!

回答2:

One important thing was not still covered. It is true that a description comes from the help_text attribute, but this is not enough. I have found that the schema generator rely on view's queryset attribute to determine a model. So, keep in mind that you need define it even if you don't need it. For example in case of using APIView.