api-guidelines VS Swashbuckle.AspNetCore

📝 "Microsoft REST API Guidelines" [link]

This is a great, thorough and in-depth document from Microsoft: https://github.com/microsoft/api-guidelines/blob/vNext/Guidelines.md

Thing is, I made some researches this morning, and I found nowhere a "data" wrapper, not in Microsoft API best practices [FR] (client is using Microsoft APIs), not in Microsoft API guidelines, not in OpenAPI offical specifications, nowhere in any blog I found this morning.

Microsoft REST API guidelines

I'm working on a web API where I'd like to follow the Microsoft API Guidelines. I thought this would be easy, because surely there would be plenty of libraries out there to support their guidelines, maybe Microsoft even has one out there (I thought). I haven't been able to find any.

It isn't where it needs to be. Notably, it cannot out-of-the-box handle open generic data types. There's also plenty of issues logged for this library. - Personally, that makes me think the approach is overly complicated and doesn't do its job as well as it should.

I have been checking all the sites about web api swagger to file but it seems theres some issue exporting swagger file on net 6.. any one can help us on this issue? https://github.com/domaindrivendev/Swashbuckle.AspNetCore/issues/2585

Also, there are multiple open bugs regarding memory utilization issues with Swagger, such as this one.

Hi there. I had an interesting task: to update the Swashbuckle.AspNetCore version from "4.0.1" to "6.2.3". It looked very simple but it was not what it looked like. The main problem was breaking changes which happened when passing from version 4 to version 5. Swashbuckle.AspNetCore began to use Swagger/OpenAPI version v3 instead of OpenAPI v2. The project makes use of NSwag to generate httpClient for getting data from another microservice. Any attempt to regenerate auto generated code changed it after updating Swashbuckle.AspNetCore version. These caused a lot of build errors. I should have decreased differencies between the new code and old one. Main difference which cause incompatibility in the project were:

Swashbuckle Github repo

Swashbuckle.AspNetCore

Trying to generate swagger from the compiled dll using this command with the swagger CLI:

Swashbuckle Swagger

That’s exactly what I meant. There’s about 0 maintenance required most of the time. Take a look at their official nuget GitHub page. This should work out of the box with ASP.NET core 3.0 and greater. For 5.0 onwards, the MVC template comes pre-configured with it.

In Swashbuckle you can do this as described here: https://github.com/domaindrivendev/Swashbuckle.AspNetCore#generate-multiple-swagger-documents