...
- 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
...
- 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
...