Mixing code with documentation is one concern. Another issue is that extracting the information needed to create a Swagger from source code is hard, especially

Mixing code with documentation is one concern. Another issue is that extracting the information needed to create a Swagger from source code is hard, especially when using dynamic languages (JavaScript, Python). One approach is to use dedicated annotators to relate code with parts of an API spec - but then you have the first problem again...