From 3a395dee7ce4a1030972e29b3c3100d396a24abf Mon Sep 17 00:00:00 2001 From: mohamed ali Date: Wed, 7 Oct 2026 13:19:14 +0000 Subject: [PATCH] Fix broken link to viewset docstring sections in docs The 'Documenting your API' topic pointed viewset users at a 'Schemas as documentation: Examples' section that no longer exists in the schemas guide, leaving the docstring sections feature undocumented. Describe it inline with an example, and clarify that the sections apply to the generated OpenAPI schema, while the browsable API shows the whole docstring. --- docs/topics/documenting-your-api.md | 14 ++++++++++++-- 1 file changed, 12 insertions(+), 2 deletions(-) diff --git a/docs/topics/documenting-your-api.md b/docs/topics/documenting-your-api.md index f4fee104bc..47dbf57e3e 100644 --- a/docs/topics/documenting-your-api.md +++ b/docs/topics/documenting-your-api.md @@ -194,7 +194,18 @@ If the python `Markdown` library is installed, then [markdown syntax][markdown] [ref]: http://example.com/activating-accounts """ -Note that when using viewsets the basic docstring is used for all generated views. To provide descriptions for each view, such as for the list and retrieve views, use docstring sections as described in [Schemas as documentation: Examples][schemas-examples]. +Note that when using viewsets the basic docstring is used for all generated views in the browsable API. To give each action its own description in the generated OpenAPI schema, split the docstring into sections named after the actions. Actions without a section of their own use the text before the first section. + + class UserViewSet(viewsets.ModelViewSet): + """ + General description, used for actions without their own section. + + list: + Return a list of all users. + + retrieve: + Return the given user. + """ #### The `OPTIONS` method @@ -229,7 +240,6 @@ To implement a hypermedia API you'll need to decide on an appropriate media type [hypermedia-docs]: rest-hypermedia-hateoas.md [metadata-docs]: ../api-guide/metadata.md -[schemas-examples]: ../api-guide/schemas.md#examples [image-drf-yasg]: ../img/drf-yasg.png [image-self-describing-api]: ../img/self-describing.png