...
- When initially invoking the Swagger url, it reads all XML documentation comments from all public methods representing API endpoints and generates "openapi" specification file (swagger.json)
- This file serves as input for Swagger UI (that means Swagger UI doesn't dynamically reflect current source code but only shows a content of openapi spec. file generated out of current XML comments)
- You can authorize yourself and execute BimPlus API requests directly from within Swagger UI, for more details see How to call BimPlus API from Swagger
XML Documentation comments
...
GitHub Copilot is integrated into IDE (Visual Studio) as an interactive assistant (chat console) that allows XML comments generation for a given contextual scope (i.e. selected method or entire controller).
Example :
- set contextual scope to the appropriate controller : # AttachmentLinksController.cs
- ask the Copilot to generate XML comments : "generate document comments including response codes
...
- as <returns> tags, producesresponsetype attributes"
- ask the Copilot to add more detailed remarks : "
...
- then add <remarks> tag containing more detailed explanation of the method purpose"
- then preview the suggested changes and accept them
...
- if the generated <remarks> section is not detailed enough, repeat the last steps or use reduced contextual scope (select a single method instead of the entire controller)
- commit the changes to source code repository
- after deploying to DEV environment the updated content will be visible in Swagger UI
...
- To add controller or method specific query parameter, use [QueryParameter] attribute (see example below). Parameter type and description should be entered directly when adding the attribute.
... and this is how it looks like in Swagger UI
- To add general purpose query parameter(s) that can be reused throughout multiple controllers, use [QueryParameters] attribute, typically paging query parameters, etc ... (see example below). Parameter type and description is predefined in this class : https://git.allplan.com/projects/SRVC/repos/api/browse/src/BimPlus.Server.Web/Core/QueryParametersAttribute.cs
... and this is how it looks like in Swagger UI
Adding optional request body
As mentioned above, optional request body being parsed dynamically is not recognized by the AI tool while generating XML Documentation comments. For that purpose we can use [SwaggerOperationFilter] attribute to decorate the API endpoint method. This filter attribute is implemented here : https://git.allplan. in progress
Adding conditional headers
... in progress
How to keep Swagger documentation up to date
...
com/projects/SRVC/repos/api/browse/src/BimPlus.Server.Web/swagger/OptionalRequestBodyFilter.cs
- To add optional request body, use the attribute with the appropriate Dto (see the example below)
... and this is how it looks like in Swagger UI
Adding conditional headers
In order to display required request headers in the Swagger UI (for example "Authorization" header that requires Bearer token to be used for secure calls) we can use [BimAuthenticate] attribute to decorate the API endpoint method.
See implementation here
- Here is an example of the attribute usage :
- and here is an example how it looks like in Swagger UI
How to keep Swagger documentation up to date
Swagger documentation is now finished for all controllers and all public methods representing API endpoints (except for controllers decorated by [ApiExplorerSettings(IgnoreApi=true)] attribute that are hidden in Swagger UI for security reasons).
Now the question is how to keep the Swagger documentation up to date,
There was an idea to try to generate the OpenAPI specification from the scratch from recent sources (by ignoring the existing XML Documentation comments) but currently this is not possible by means of GitHub Copilot because :
- it is not possible to schedule this action from outside the IDE (GitHub Copilot does not have its own command line interface).
- it is not possible to generate OpenAPI specification for bigger contextual scope (I've tried it for a smaller controller but for multiple controllers or the entire solution it would definitely not produce any usable result)
- sources are not optimized for that, it would be necessary to refactor all parts where optional query parameters and request body are parsed dynamically (GitHub Copilot is only able to recognize them if they are defined as method parameters)
I can try to investigate if any other tool could be used for that but for now I do not have any solution for that.
Other option would be to ask developers to keep the XML Documentation comments up to date whenever making changes in the source code. There is no need to generate the comments again, just add response code or query parameter into XML comments if needed, or modify the existing <remarks> section to keep the method description up to date.
Recommendations for developers
- please keep the documentation up to date by yourself, it is a responsibility of each developer to keep the documentation aligned to recent source code changes
- add or modify the <response> tag(s) and[ProduceResponseType] attribute(s) in the existing XML comments according to recent source code changes
- add or modify the [QueryParameter] and/or [QueryParameters] attribute in the existing XML comments if needed
- add the [SwaggerOperationFilter] attribute into the existing XML comments if optional request body is needed
- modify the <remarks> section in the existing XML comments according to recent changes in the method behavior
- generate the XML Documentation comments for newly created API endpoint(s) using GitHub Copilot as described above