Issue #3283
closed
Descriptions for actions are based on docstring
Description
Looks like drf maps docstring for viewset actions to a description field in the api schema. For example, our artifacts delete action looks like this in the api schema:
"delete": {
"_type": "link",
"action": "delete",
"description": "Remove :class:`~pulpcore.app.models.Artifact` only if it is not associated with any\n`~pulpcore.app.models.Content`\n\nArgs:\n request (:class:`rest_framework.request.Request`): request containing JSON payload\n with information about the artifact being deleted.\n pk (:class:`uuid.UUID`): Unique id of the artifact being deleted.\n\nReturns:\n :class:`rest_framework.response.Response` with a 204 status code in case of\n successful deletion, 409 status code if deletion is not allowed.",
...
}
This is from the docstring on the action here:
https://github.com/pulp/pulp/blob/3.0-dev/pulpcore/pulpcore/app/viewsets/content.py#L86-L98
This is probably not very friendly for API users. Not sure what the solution here is.
Other endpoints with this problem include content create, status, etc.
Related issues
Updated by daviddavis over 6 years ago
- Subject changed from Documentation for actions are hard to parse to Descriptions for actions are hard to parse and expose internal implementation
Updated by bmbouter over 6 years ago
We have a similar issue on errors that are recorded on Tasks. They are a single string with a bunch of '\n' characters in it. It looks bad visually. I think it's ok though because it's for machines, and when they render it for humans the '\n' will become newlines and it will look nice.
If I've missed the essence of this issue disregard this comment. :)
Updated by daviddavis over 6 years ago
bmbouter, the '\n' characters are only part of the problem. The other problem is that the description contains function arguments/return values/etc (request, response, etc) that only make sense if you look at the function. In our api schema, they don't make sense at all to our users.
Updated by daviddavis over 6 years ago
- Subject changed from Descriptions for actions are hard to parse and expose internal implementation to Descriptions for actions are based on docstring
Updated by daviddavis over 6 years ago
bizhang mentioned that it's possible to maybe use a named section in our docstring to override these descriptions. See:
http://www.django-rest-framework.org/api-guide/schemas/#schemas-as-documentation
If that doesn't work, we could also use some custom schema generation.
Updated by daviddavis over 6 years ago
- Blocks Story #3218: As an authenticated user, I can list repository version content, added content, removed content added
Updated by daviddavis over 6 years ago
I tried using alternative ways to document the viewset actions per comment #6 but they don't work.
Looking over the docstring we have in our viewsets, they really don't seem to add a lot of value. They seem to mostly document the internals of DRF. I'm tempted to remove them.
Updated by daviddavis over 6 years ago
- Status changed from NEW to POST
- Assignee set to daviddavis
Updated by bmbouter over 4 years ago
- Status changed from MODIFIED to CLOSED - CURRENTRELEASE
.