📝🎨 Review and improve swagger docs - descriptions, context, and examples

A lot of development has been done. Now's a good time to review the Swagger docs and improve descriptions/summaries to be more informatives; parameters formatted/described in standardised way; and adding some example flows where relevant.