search

RicoSuter / NSwag

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

NSwag.Annotations support for CSharpControllerGenerator #2303

Open EndlessDelirium opened 5 years ago

EndlessDelirium commented 5 years ago

Would be great if CSharpControllerGenerator would offer the option to include the additional info from the OpenAPI document as NSwag.Annotations so that when generating an OpenAPI doc from code we would end up with basically the same file.

RicoSuter commented 5 years ago

The idea is that the generated output is completely independently usable without NSwag (dependencies).

generating an OpenAPI doc from code we would end up with basically the same file.

Somehow this makes sense, but why would you need that?

EndlessDelirium commented 5 years ago

Your point about minimizing dependencies is certainly a very valid one and I don't think that what I'm suggesting here should be the default option. Neither is this needed in a perfect world. But since we're all in a hurry it's not that uncommon that in-code changes are made to what originally started as design first OpenAPI doc. It's simply quicker to go code-first for smaller improvements. If what I'm suggesting is implemented, users have the peace of mind to switch between design-first and code-first at any time.

(Sorry for the delayed reply, I was in vacation)

RicoSuter commented 5 years ago

Ok, so the scenario is to first do schema first generation and then switch to code first? Makes sense...

At this time most of the NSwag are no longer needed as there are replacements in ASP.NET Core for most of them (eg OpenApiResponse vs ProducesResponseType).

We should first generate these native attributes and then see what’s missing.

EndlessDelirium commented 5 years ago

Another choice for code-first would be https://github.com/domaindrivendev/Swashbuckle.AspNetCore. Additionally, Microsoft has a preview project that leverages XML documentation (https://github.com/microsoft/OpenAPI.NET.CSharpAnnotations). That one however doesn't seem to gain much traction?

RicoSuter commented 5 years ago

NSwag already provides all functionality of these projects (code first). I’m always suggesting to use mostly native attributes (you can achieve most with them) so that you are flexible which tool to use later..