search

RicoSuter / NSwag

The Swagger/OpenAPI toolchain for .NET, ASP.NET Core and TypeScript.
http://NSwag.org
MIT License
6.63k stars 1.23k forks source link

The wiki/documentation you have on various things are out of date and were not update since 2019 #4934

Open vamsidogiparthi opened 2 weeks ago

vamsidogiparthi commented 2 weeks ago

Hi, Your documentation is very outdated and not easy to understand as well. Example below wiki document is completely outofdate as we are no longer using webApiToDocument for .NET 6 or plus. Nor assembly paths etc. We have to search many sites and forums to even understand what we have to do as part of 14.08 to make it work. As .NET or microsoft is recommending NSwag for everyone. You should be vigilant enough to update your wiki as well as provide clear instructions for every use case.

Also, you nswag new creates a json document with NetCore21 framework and not document generation setting. Which is another suggestion from our side.

https://github.com/RicoSuter/NSwag/wiki/NSwag-Configuration-Document

ahl-trifork commented 2 weeks ago

Just spent a couple of hours trying to solve issues with generated default values and nullability. To find the "generateOptionalPropertiesAsNullable" property, which solved the issues for me, i had to download NSwag studio, save a dummy config and find the property in the saved .nswag file, because the documentation is out of date.

diegosasw commented 1 day ago

I agree. Coming from swashbuckle I am still unable to find out how Nswag works regarding generation of open API JSON out of the app (preferably .net8+). Is there any working sample, somewhere, where I could see how to extract open API Json during CI/CD pipeline without having to run the app?

vamsidogiparthi commented 1 day ago

@diegosasw , @ahl-trifork I have been writing some medium articles on this very topic. See if those help you out in anyway. All of them are attached with a working github repos. so, might give you some heads up. If you need any further help. Let me know and I will be adding some complex use cases soon to my medium.

@diegosasw in your scenario my article related to MSbuild will help you with u r use case

https://medium.com/@vamsidogiparthi/learn-and-understand-how-to-generate-swagger-json-via-msbuild-and-net-8-with-simple-start-up-d7ad6c3cf74b