Introduction
The OpenAPI Specification (OAS) defines a standard, language-agnostic interface to HTTP APIs which allows both humans and computers to discover and understand the capabilities of the service without access to source code, documentation, or through network traffic inspection. When properly defined, a consumer can understand and interact with the remote service with a minimal amount of implementation logic ...
For more details see https://swagger.io/specification/
BimPlus API Swagger url
The BimPlus API Swagger is accessible directly via the same url where API is deployed on DEV environment : https://api-dev.bimplus.net/swagger/index.html
BimPlus API Swagger configuration
The BimPlus API Swagger is configured in the following class : https://git.allplan.com/projects/SRVC/repos/api/browse/src/BimPlus.Server.Web/Program.cs
...
How it works
- 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)
XML Documentation comments
C# documentation comments use XML elements to define the structure of the output documentation. For more details see the following reference :
https://learn.microsoft.com/en-us/dotnet/csharp/language-reference/xmldoc/recommended-tags
To generate a minimum content (just to avoid build warnings) type 3x "slash" key but this is not really enough for serious documentation (here only the <summary> tag, <returns> tag and method parameters are generated)
More detailed XML comments can be added either manually or can be generated by AI tool. See the following example describing how detailed XML comments are reflected in Swagger UI
Using AI Tool (GitHub Copilot) to generate 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 and producesresponsetype"
- ask the Copilot to add more detailed remarks : "add remarks to existing document coments, containing more detailed explanation of the method purpose"
- then preview the suggested changes and accept them
- 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 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)
Adding optional query parameters
As mentioned above, optional query parameters that are parsed dynamically are not recognized by the AI tool while generating XML Documentation comments. As a workaround, we introduced two new attributes that can be used to decorate API endpoint method in order to display a given query parameter(s) 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.
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.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)
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
https://git.allplan.com/projects/SRVC/repos/api/browse/src/BimPlus.Server.Web/Core/BimAuthenticate.cs
https://git.allplan.com/projects/SRVC/repos/api/browse/src/BimPlus.Server.Web/swagger/ConditionalHeaderParameter.cs
- 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
... in progress