Django-rest-framework: Set view function's docstring to descriptions of coreapi.Link on SchemaGenerator

[c-bata]

Checklist

• [x] I have verified that that issue exists against the master branch of Django REST framework.
• [x] I have searched for similar issues in both open and closed tickets and cannot find a duplicate.
• [x] This is not a usage question. (Those should be directed to the discussion group instead.)
• [x] This cannot be dealt with as a third party library. (We prefer new functionality to be in the form of third party libraries where possible.)
• [x] I have reduced the issue to the simplest possible case.
• [ ] I have included a failing test as a pull request. (If you are unable to do so we can still accept the issue.)
  

  Proposal

Hi, It's a proposal of SchemaGenerator.
Now, SchamaGenerator set only url, action, encoding and fields at following source code:

https://github.com/tomchristie/django-rest-framework/blob/master/rest_framework/schemas.py#L220-L242

I think it's very useful to set a docstring to a description of coreapi.Link like:

    def get_link(self, path, method, callback, view):
        """
        Return a `coreapi.Link` instance for the given endpoint.
        """
        :

        return coreapi.Link(
            url=urlparse.urljoin(self.url, path),
            action=method.lower(),
            encoding=encoding,
            fields=fields,
            description=callback.__doc__  # <= here
        )

[decentral1se]

This is being covered in https://github.com/tomchristie/django-rest-framework/issues/4241.

[tomchristie]

The issue with this is that with a view you'd end up with the same descriptions for each of GET, POST, ... although the actions are different.

Or with a viewset, you'd end up with the same descriptions for all the actions on the viewset.

Not obvious what a good way to resolve this would be.

You _could_ use the get() method docstrings or action method docstrings, tho in class based views/viewsets you'll very often have generic implementations, and the docstrings may not be any use.

[tomchristie]

@lwm Agree - although let's leave this _specific_ issue open for now, for further discussion.

[c-bata]

@tomchristie You're right. Thank you for your consideration.

[Skorpyon]

It may use action handler docstring from actions map:

def create(self, request, **kwargs):
    """
    Create new instance of Icecream.
    """

def delete(self, request, **kwargs):
    """
    Remove Icecream.
    __Warning:__ if Icecream have attached candies, you should remove candies first.
    """

[ghost]

@Skorpyon what about generic views?
@tomchristie will this be ready by 3.5.0 due date? is there anyway to help?

[tomchristie]

@danield137

Having your company sign up to a paid plan is the most impactful way to help collaborate. I'm working full time on the project right now. And yes this issue oughta come up prior to 3.5 but it's not clear yet what the resolution will be.

[abondar]

@danield137 For documenting generic views I use this implementation for SchemaGenerator

        class SchemaGenerator(schemas.SchemaGenerator):
            def get_link(self, path, method, callback, view):
                fields = self.get_path_fields(path, method, callback, view)
                fields += self.get_serializer_fields(path, method, callback, view)
                fields += self.get_pagination_fields(path, method, callback, view)
                fields += self.get_filter_fields(path, method, callback, view)

                if fields and any([field.location in ('form', 'body') for field in fields]):
                    encoding = self.get_encoding(path, method, callback, view)
                else:
                    encoding = None

                if self.url and path.startswith('/'):
                    path = path[1:]

                return coreapi.Link(
                    url=urlparse.urljoin(self.url, path),
                    action=method.lower(),
                    encoding=encoding,
                    fields=fields,
                    description=view.__doc__
                )

[ghost]

@Zeliboba5 I am aware of this as a possible workaround, but what I mostly care about is arguments and return types and descriptions.
For now, I wrote it manually instead of generating it from code.

[smcoll]

Version 1.x of django-rest-swagger supported YAML docs like this:

class MyViewSet(viewsets.ModelViewSet):
    """
    <shared description>
    ---
    create:
        parameters:
            - name: foo
              required: true
    update:
        parameters:
            - name: foo
              required: false
    myaction:
        parameters:
            - name: bar
              required: true
    """

But essentially, you could either add your docs in each method itself (like @Skorpyon mentioned) or you could bundle the docs in the viewset's docstring.

[tomchristie]

Now resolved in the upcoming version-3-5 branch.

[c-bata]

Thank you!!