Project

Profile

Help

Issue #3283

Descriptions for actions are based on docstring

Added by daviddavis almost 2 years ago. Updated 7 months ago.

Status:
MODIFIED
Priority:
Normal
Assignee:
Category:
-
Sprint/Milestone:
Start date:
Due date:
Severity:
2. Medium
Version:
Platform Release:
Blocks Release:
OS:
Backwards Incompatible:
No
Triaged:
No
Groomed:
No
Sprint Candidate:
No
Tags:
QA Contact:
Complexity:
Smash Test:
Verified:
No
Verification Required:
No
Sprint:

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

Blocks Pulp - Story #3218: As an authenticated user, I can list repository version content, added content, removed content MODIFIED Actions

History

#1 Updated by daviddavis almost 2 years ago

  • Subject changed from Documentation for actions are hard to parse to Descriptions for actions are hard to parse and expose internal implementation

#2 Updated by daviddavis almost 2 years ago

  • Description updated (diff)

#3 Updated by bmbouter almost 2 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. :)

#4 Updated by daviddavis almost 2 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.

#5 Updated by daviddavis almost 2 years ago

  • Subject changed from Descriptions for actions are hard to parse and expose internal implementation to Descriptions for actions are based on docstring

#6 Updated by daviddavis almost 2 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.

#7 Updated by daviddavis almost 2 years ago

  • Blocks Story #3218: As an authenticated user, I can list repository version content, added content, removed content added

#8 Updated by daviddavis almost 2 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.

#9 Updated by daviddavis almost 2 years ago

  • Status changed from NEW to POST
  • Assignee set to daviddavis

#10 Updated by daviddavis almost 2 years ago

  • Status changed from POST to MODIFIED

#11 Updated by dkliban@redhat.com over 1 year ago

  • Sprint/Milestone set to 3.0

#12 Updated by bmbouter 7 months ago

  • Tags deleted (Pulp 3, Pulp 3 MVP)

Please register to edit this issue

Also available in: Atom PDF