Just recently, I received a bug report for an ASP.NET Core Web API application I'm maintaining because of incorrectly rendered schema for a response in the Swagger UI. The culprit ended up being an old version of Swagger UI used by an old version of Swashbuckle.
The .NET Feature Management libraries are great for toggling the availability of ASP.NET Web API endpoints with feature flags. Unfortunately, such endpoints will still show up in the generated OpenAPI specification even when the feature flag is disabled. To hide them, you need to implement a custom filter for Swashbuckle.
By default, the OpenAPI specification created by Swashbuckle for ASP.NET Core web API doesn't include the descriptions for endpoints and models from XML comments. There are step-by-step instructions how to add them in the documentation, but even then there will be no descriptions for models from other assemblies.
I recently had an issue with optional route parameters in ASP.NET Core Web API not showing as such in the Open API specification generated by Swashbuckle. The most comprehensive source of information I could find on this issue was a blog post, which I used as a basis for further research.
The biggest advantage of having a formal description for a RESTful API is the ability to programmatically generate client-side code for calling the service. Unfortunately, it turned out that Swagger tooling still leaves much to be desired, at least for generating TypeScript Angular code.