I personally like the MSDN documentation style. Full outline of all the methods, explanations of what they do, links to objects you pass in, list of expected exceptions to be thrown.

More on reddit.com

Developers often don't understand the value of these tools. The overwhelming majority of devs that I've worked with did not have any experience with using swagger to generate client code for APIs. They don't usually lean on it for documentation since they know how the api works. They largely just viewed swagger as a test tool for people too lazy to install postman. Devs are also lazy. Documentation is work, and the kind of work that no one enjoys. Companies are extremely short sighted when it comes to documentation. Getting the work done a few hours faster right is high priority. Worrying about people who will be trying to understand things a year or two from now is low priority. Good managers and leads will hopefully push for documentation even if they company doesn't value it that much, but often they're fighting a losing battle. More on reddit.com

Validate the responses against the schema and throw errors if they don’t match rather than serving an incorrect result. More on reddit.com

Doesn’t FastAPI already have a way to block the docs More on reddit.com