...
- it is an interactive assistant integrated into IDE (Visual Studio) but it does not have a command line interface (CLI) and thus it is not possible to generate the Swagger documentation "on the fly" (from outside the IDE) based on recent sources without human interaction (it helps you to generate XML Documentation comments but you must accept and commit the changes manually)
- it has a problem if the contextual scope is too big, for example it can generate XML Documentation comments for a single controller, but not for the entire solution (you are asked to rephrase your request or to reduce the contextual scope if the result is supposed to be too big)
- it is not able to distinguish optional query parameters that are not defined as method parameters but are parsed dynamically deeper inside call hierarchy (controller, service or even repository layer)
- it is not able to distinguish optional request body that is not defined as method parameter but is parsed dynamically (similar to optional query parameters parsed dynamically)
- sometimes it gives results that are not 100% correct so you must be very careful when accepting the changes, for example the recommended success response code for "Delete" method is 204, but if the current code implementation returns 200, it nevertheless generates <response code="204"> in a few cases (not always but sometimes the generated documentation is incorrect)