Add descriptions to fields and responses #786
Conversation
…string Signed-off-by: Paul Wayper <paulway@redhat.com>
Signed-off-by: Paul Wayper <paulway@redhat.com>
|
@PaulWay thanks for the time put into this. I've corrected the implementation and updated some of the test schema. At the moment the unit tests are not functionally testing behaviour, rather they match the test output to a correct test schema. Since I've updated the 'correct' schema to include descriptions I'd like some additional reviewers to verify the changes before merging. More specifically, are the definitions that are now in |
JoelLefkowitz
added
1.22.x
There was a problem hiding this comment.
@PaulWay good job! I think these changes will help the schema to be more understandable for developers.
| type=openapi.TYPE_OBJECT, | ||
| properties=properties, | ||
| required=required or None | ||
| ) |
There was a problem hiding this comment.
@PaulWay SwaggerType is, in fact, drf_yasg.openapi.Schema. Maybe it's better to insert description separately?
if description:
result.description = descriptionAnother way:
result = SwaggerType(
...
description=description or None
)| @@ -557,7 +592,7 @@ def field_to_swagger_object(self, field, swagger_object_type, use_references, ** | |||
| if not isinstance(field, serializers.SerializerMethodField): | |||
| return NotHandled | |||
|
|
|||
| method = getattr(field.parent, field.method_name, None) | |||
| method = getattr(field.parent, field.method_name) | |||
There was a problem hiding this comment.
Why? Without default value this code will raise AttributeError.
| description = getattr(field, 'description', getattr(field, '__doc__')) | ||
|
|
||
| if description is None and hasattr(field, 'Meta') and hasattr(field.Meta, 'model') and hasattr(field.Meta.model, '__doc__'): | ||
| description = field.Meta.model.__doc__ |
There was a problem hiding this comment.
This doesn't seem like a good idea, because the Model is an internal entity and may contain help that may not be relevant to the API at all.
This was added to drf-yasg2 a while back and didn't get backported into drf-yasg.