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

[hansmbakker]

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]

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]

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]

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]

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]

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.

[adrianhall]

Currently in progress.

[adrianhall]

Turns out that the OpenAPI library works out of the box (I know - I'm shocked) without the need for additional transformers; but only if the entire project is .NET 9. I'm going to produce a test suite to ensure that is the case and there are no additional corner cases (like read-only and sub-classes controllers working); but this is straight forward supported at this point.

[adrianhall]

... spoke too soon. There is one schema change that needs to be done (which will take a SchemaTransformer). The "nextLink" of the EntityPage (where Entity is replaced by the name of your entity) is defined as a "uri" format, but it's a query string instead.

Thus the tasks are:

• Create a CommunityToolkit.Datasync.Server.OpenApi library with the schema transformer (and extension methods) in it.
• Create a test that generates the test service, reads the openapi.json and compares against the expected openapi.json file

While the AddOpenApi/MapOpenApi work for a standard web host builder, they don't work for the TestServer, so I may have to adjust the test service accordingly. Investigation is ongoing.

[adrianhall]

Follow-up on this. Most of the work has been done.

The problem I encountered was that I cannot provide the "schema" for each entity name. This will apparently get fixed in .NET 10 (and not before). I've opened up a tracking issue here #266 which gives an explainer on why not.

My advice is to wait for .NET 10 before using OpenApi services other than NSwag and Swashbuckle.