Swagger / OpenAPI and dotnet client for the api

[lynkz-matt-psaltis]

Came across this amazing implementation today! Great to see C# and dotnet getting some awesome platforms like this nice work.

Wanted to suggest swagger enabled documentation and possibly a dotnet client to interface with the backend api.

Love it!

[ShreyasZare]

Thanks for the compliments! Will take a look at swagger. A dotnet API client will be nice to have. Will try to have something when core and planned features are implemented.

[matt-psaltis]

@ShreyasZare are you open to a PR for any of this? If there's a large amount of churn it might not make sense. I have need to at least partially implement a dotnet client if that would be helpful?

[ShreyasZare]

Yes, since the DNS Server API client will be an separate VS project in the repo, its fine if you try to create a minimal implementation and create a PR for it. Later on, as required, the API methods can be added and maintained.

[matt-psaltis]

Awesome! Can I ask, was aspnet core avoided as a specific decision? Swagger support would be a 10 minute job on aspnet core :D

[ShreyasZare]

Awesome! Can I ask, was aspnet core avoided as a specific decision? Swagger support would be a 10 minute job on aspnet core :D

This is since when the project was started, it was in .NET Framework and dotnet core was new. Later, the project was partly upgraded to use dotnet core using .NET Standard such that on windows it used .NET Framework and on Linux it used dotnet core. The issue was that earlier versions of dotnet didnt support running Window Service so for Windows, .NET Framework was only option. The web server used was HttpListener which worked with both .NET Framework and dotnet. Once .NET 5 was released, complete project was migrated.

Another issue is that the current implementation allows changing TLS certificates at runtime without need for restarting the web server. Similarly, the DNS server can change stop and start the web service on a different IP address without need to restart the DNS server. This is something I have not found a solution in ASP.NET core. Also with the current design, its DNS server that is running a built-in web server while with ASP.NET core, its a web server which will internally run the DNS server.

[matt-psaltis]

Yep makes complete sense, if you're open to discussing a migrate happy to help out where I can.

In terms of dynamic TLS resolution that's available now: https://learn.microsoft.com/en-us/aspnet/core/fundamentals/servers/kestrel/endpoints?view=aspnetcore-6.0#sni-with-servercertificateselector-1

For port changes, The WebHost would have to be stopped by the dns server and started again on the new ports using the listen options at the link above.

[ShreyasZare]

Thanks for the link. Will try to run some experiments with it to test it out. There is already an open issue to replace the web server due to issues with the current one described here.

[bluegrassiot]

Adding swagger would be really nice. I am trying to develop an application in JS that will use the API and it would be very nice to have the json documentation for the API so that I could easily generate the client side code using Swagger Codegen or to at least import into PostMan for development purposes. Any updates on this?

[bluegrassiot]

I started to add this, but I don't know that I will have time to complete it. For reference this pretty much tells you how to do it: https://learn.microsoft.com/en-us/aspnet/core/tutorials/getting-started-with-swashbuckle?view=aspnetcore-7.0&tabs=visual-studio

I had to add the ResolveConflictingActions in AddSwaggerGen in order for it to serve the swagger page correctly.

builder.Services.AddEndpointsApiExplorer(); builder.Services.AddSwaggerGen(c => { c.ResolveConflictingActions(apiDescriptions => apiDescriptions.First()); c.IgnoreObsoleteActions(); c.IgnoreObsoleteProperties(); c.CustomSchemaIds(type => type.FullName); });

` _webService = builder.Build();

        _webService.UseDeveloperExceptionPage();
        _webService.UseSwagger();
        _webService.UseSwaggerUI(); `

Then I could see the page at: http://localhost:5380/swagger/index.html

Authorization would need to be added and then also all of the parameters and message bodies.

It didn't take me too long to get this far.

[ShreyasZare]

Adding swagger would be really nice. I am trying to develop an application in JS that will use the API and it would be very nice to have the json documentation for the API so that I could easily generate the client side code using Swagger Codegen or to at least import into PostMan for development purposes. Any updates on this?

Thanks for asking. From what I understand, to support Swagger such that it would generate the documentation automatically will require rewriting the entire API backend code in the way it expects. So this does not seem feasible to be implemented.