Feature request: Write and edit API endpoint descriptions

[ivanagas]

I want to add a description to an endpoint (AKA a set of operations) like Stripe does here: https://docs.stripe.com/api/charges

The current way to add descriptions to API endpoints is to use a doc string on the viewset class. I tried to do this, but it turns out this doesn't really work:

1. Adding a doc string to a viewset class adds it as a description to all the operations rather than a description to the path.
2. The way the endpoint description is generated is by getting the description from the first operation
3. Adding extend_schema() to an operation (like we do in query) overwrites the operation description set by the viewset docstring.
4. drf-spectacular (the way we generate the API schema) doesn't support generating path descriptions. The closest seems to be extend_view_schema() but this seems to just add new operations rather a description. To make it do something else would require a bunch of custom processing code.
5. Adding links to posthog.com in the posthog repo code looks ugly

I'm not sure what the best way to do this is, I'm happy to try to figure it out if you point me in the right direction. I think it should be editable in the posthog.com repo.

[smallbrownbike]

What do you think about this?

Basically, add an MDX file (named after the endpoint ID's name) to the corresponding folder its page would belong to. Then, the description in the MDX file will only appear under the specified endpoint. This is like our MDX setup, except the file name will determine which endpoint the MDX contents appear on.

So, for adding a description to the "list annotations" endpoint, you'd create a new file - contents/docs/api/annotations/annotations_list.mdx

Then, whatever you add to that file will appear under that endpoint only (see screenshot below). Since you can also add React components, we can start making new endpoint-specific components to recommend guides or reference other helpful info, too!

[ivanagas]

Yes, this would be perfect