search

RicoSuter / NSwag

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

IDE Native configuration for OpenApiReference #3789

Open hayhay27 opened 2 years ago

hayhay27 commented 2 years ago

Discussion for PR https://github.com/RicoSuter/NSwag/pull/3790

Investigating aproaches (in #3636) for cross-platfrom lightweight configuration I found useful feature in VS. Property window customizable via PropertyPageSchema. This approach already used in Grpc.Tools and Microsoft.Extensions.ApiDescription.Client

I made a small project to prove the concept here Then I realized that this feature not supported by Rider and open issue on youtrack (likes are welcome).

So at this time customizable property window supported only in Visual Studio but we can change that.

RicoSuter commented 2 years ago

Ref: It would look like this:

image

hayhay27 commented 2 years ago

Better late than never

Finally I added property page support. You can enable it with property NSwagPropertyPageType=CSharp|TypeScript

Another one feature is compile-time generation for controllers (same as for OpenApiReference). Add property NSwagControllerPropertyPageEnabled=true in project where you want to generate controller.

@RicoSuter do we need to provide samples for this feature?

hayhay27 commented 2 years ago

How to use this feature (supported only in VisualStudio for Windows but there is issue for Rider)

OpenApiReference

  1. Add OpenApi specification to your project (for example this one)
  2. Add NSwag.ApiDescription.Client package reference to your project - dotnet add package NSwag.ApiDescription.Client
  3. Add property <NSwagPropertyPageType>CSharp</NSwagPropertyPageType> for csharp generator or <NSwagPropertyPageType>TypeScript</NSwagPropertyPageType> for typescript generator
  4. Change Build Action for OpenApi specification to OpenApi File Reference
  5. Use property page to configure options

There is limitation: we cannot use property page for both languages at the same time

NSwagController (same as OpenApiReference just for openapi2cscontroller command)

  1. Add OpenApi specification to your project (for example this one)
  2. Add NSwag.MSBuild package reference to your project - dotnet add package NSwag.MSBuild
  3. Add property <NSwagControllerPropertyPageEnabled>true</NSwagControllerPropertyPageEnabled>
  4. Change Build Action for OpenApi specification to NSwag Controller File Reference
  5. Use property page to configure options
  6. Also you can specify common properties via project property <NSwagControllerGenerateCodeOptions>/SomeCommonProperty:value</NSwagControllerGenerateCodeOptions>
pinkfloydx33 commented 2 years ago

Is this available? A bit confused by the above as it makes it sound like it should work in VS. I checked the latest version and latest preview and don't see it; not sure if I just haven't configured it properly or if I'm chasing something that's not there

hayhay27 commented 2 years ago

@pinkfloydx33 Did you follow steps above?

pinkfloydx33 commented 2 years ago

I did but it didn't work. It's not a big deal though as I got what I needed. I was mainly trying to visualize all of the available options in one place--tracking them down through the docs is an incomplete maze and in some instances requires digging through source. I just ended up using the screenshot from the OP. Thanks

hayhay27 commented 2 years ago

@RicoSuter how to push PR #3790 ? What I have to do?

kvart714 commented 5 months ago

@hayhay27 are you planning to complete it? it looks very comfortable!

Now we have to use NSwagStudio as a playground, and then transfer the keys manually to OpenApiReference 😔