I'm going to answer this despite not being the parent. I've looked into this problem area 2 years apart now. The first time I came across swagger 2 and some Ruby toolings to automatically turn source code annotations (not comments) into my api docs.
I was hoping to not do this 2 years later so really looked hard into it. I was dismayed to find that all of the good looking out of the box tools required writing docs by hand, no generation! I looked back into swagger 2 and found great success this time around. A few things were important:
1. Building the API how I wanted which involved integrating docs into the actual functionality. For instance, all params and response attributes are defined in the code and then turned into documentation later.
2. Spending time to get the docs how we wanted them, not just going with the stock.
3. Not being afraid to break the spec with custom json descriptions when necessary. Not pretty but entirely functional.
We do not use swagger for auto generation or testing, only documentation. I do not think that the current swagger UI implementation is attractive and think they're missing hard by not spending more time on the design style that is trending now. The spec itself is solid.
