Add descriptions to responses.

[apollo13]

Describe the feature
@extend_schema currently lists many ways to document responses, but none of them allow setting the description. I am not sure what would be a good way to do so, maybe make the value in the dict a tuple of description & actual response?

drf-yasg did allow for this like this (not saying that I particularly like that approach):

ping_response = openapi.Response("response description", PingOutputSerializer)
@swagger_auto_schema(
    method="get",
    ...
    responses={200: ping_response},
)

Any ideas? I might be able to offer the code if there is a clear path :)

[tfranzel]

are you referring to this specific description string?

drf-spectacular/tests/test_basic.yml

Line 23 in cb810db

description: ''

this has been asked a few times before and i was not aware of the existing solution in yasg. you are however aware that the serializer docstring is in fact used? at the moment we are only missing the individual docstring on the status_code (e.g.200) level. i suppose this is useful after all. we would have to do a similar construction as yasg to support this.

[apollo13]

I was not aware that the doc string of the serializer is used. That is great to know and maybe I'll add an empty serializer -- in my case the response had status code 204 (no content) or 404 for that matter, so I didn't add a serializer at all :)

…

On Thu, Mar 25, 2021, at 21:49, T. Franzel wrote: are you referring to this specific description string? https://github.com/tfranzel/drf-spectacular/blob/cb810dbe90caf52b876efdf607cac7eba60f63bb/tests/test_basic.yml#L23 this has been asked a few times before and i was not aware of the existing solution in yasg. you are however aware that the serializer docstring is in fact used? at the moment we are only missing the individual docstring on the `status_code` (e.g.`200`) level. i suppose this is useful after all. we would have to do a similar construction as yasg to support this. — You are receiving this because you authored the thread. Reply to this email directly, view it on GitHub <#345 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAAT5CZKRRI6L3O3TJOCZFTTFOOW7ANCNFSM4ZY5FY2Q>.

[tfranzel]

@apollo13 has this been resolved for you or does the feature request remain?

[apollo13]

I haven't checked yet. But I guess that adding an empty serializer will make it show up in the schema as well, so I guess I'd still would love to see a more lightweight solution

[samfrances]

As far as I can see, the docstring from the serializer doesn't end up in the response description. Am I doing something wrong?

[tfranzel]

we now support this analog to drf-yasg.

[apollo13]

Lovely, thank you very much.

…

On Fri, Apr 2, 2021, at 01:14, T. Franzel wrote: we now support this analog to drf-yasg. — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#345 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAAT5CYPOHFJDJPCWR3TKV3TGT457ANCNFSM4ZY5FY2Q>.

[tfranzel]

closing this issue for now. feel free to comment if anything is missing or not working and we will follow-up.