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" followed by <Enter> 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
