I just saw a presentation here that touches on your question among other topics:
https://www.youtube.com/watch?v=k5ncCJBarRI&t=26m58s
-
Swagger doesn’t support hypermedia at all / it’s URI centric
-
Swagger’s method of inspecting your code can lag behind your code. It’s possible make a change in your code that Swagger fails to understand and won’t process properly until Swagger gets updated.
-
Swagger requires lot of annotation, and it’s painful to include the descriptive text you want in an api document in annotations.
-
There are just some things that Swagger can’t figure out from inspecting your code.
In any case, these are just a couple of points. The presenter does a much better job discussing it than I could.