Here is an enlightning talk about the structure : https://www.youtube.com/watch?v=azf6yzuJt54
You may also appreciate reading Swagger's tips: https://swagger.io/blog/api-documentation/best-practices-in-... and reading up on Swagger in general.