search

CommunityToolkit / Datasync

A collection of libraries that implement a client-server system used for synchronizing data from a cloud-based database.
https://communitytoolkit.github.io/Datasync/
Other
66 stars 13 forks source link

Using .NET 9's built-in OpenAPI document generation #48

Open hansmbakker opened 5 months ago

hansmbakker commented 5 months ago

Is your feature request related to a problem? Please describe. Currently third-party libraries like Swashbuckle and NSwag are needed to provide OpenAPI documentation for asp.net core based APIs

Describe the solution you'd like .NET 9 will include built-in support for OpenAPI document generation.

Describe alternatives you've considered

Additional context I understand .NET 9 is still being developed, but just wanted to put this on the backlog

hansmbakker commented 4 months ago

I see you added this to the 10.0.0 milestone - however that is more than a year away.

Would it be an option to do multi-targeting and already do something with 9.0.0 sooner?

adrianhall commented 2 months ago

Policy is that we target LTS releases. 9.0 is an STS release of dotNet.

That being said, I may produce a 9.0.0 specific library for this functionality. I just can't commit to it right now, especially as I've not seen the API work necessary as yet. If you have taken a look and can contribute the library in question, I'll happily take a look.

adrianhall commented 1 month ago

Putting a link into the issue for tracking:

https://learn.microsoft.com/en-us/aspnet/core/release-notes/aspnetcore-9.0?view=aspnetcore-8.0#openapi

I need to write a schema processor, and that can't come in until we switch the main library to .NET 10 (when the standard build of VS includes it)

hansmbakker commented 1 month ago

Given that you have separate projects like CommunityToolkit.Datasync.Server.NSwag, would it be possible to have an optional project that covers the builtin OpenAPI generation which targets .NET 9?

In my opinion, the limitation of only supporting LTS releases seems like a needless delay to new functionality. What is the driver behind this policy, and who decides about it? Other CommunityToolkit projects (e.g. CommunityToolkit/Maui) will target .NET 9 - so I find it difficult to see where this comes from.

adrianhall commented 1 month ago

MAUI tracks the MAUI releases, which advise updating to the latest STS.

The problem is that the entire environment shifts and I'm just not set up for it yet. It affects all the tests, builds, pipelines, and releases. It's not a small effort on the infrastructure side. As the maintainer, I can't commit to doing it.

If you would like to take a copy of the NSwag project and release a new one for OpenApi support in .NET 9, I will review and work with you to get it into the project. I'm not saying, in other words, that "you must wait until .NET 10 is out!" - I'm saying "I will not be working on it until the LTS comes out"

If you provide a PR with the library, tests, and a sample, I'll see what I can do on the infrastructure side to support it.