...
- commit the changes to source code repository
- after deploying to DEV environment the updated content will be visible in Swagger UI
AI Tool (GitHub Copilot) limitations
GitHub Copilot is a great tool to help somebody who is not familiar with the API to explain each method purpose and to generate detailed XML documentation for each API endpoint. However, it has some limitations and you must be careful when using it.
- 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 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 within the 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)