Request: OpenAPI/Swagger Source Generator

[JohnGalt1717]

Especially given Aspire and when using it, being able to spin up a micro service separately to build openapi docs is not easy anymore, Swashbuckle dying and NSwag not supporting most of V3.1 spec (including even Enums properly), it would be nice to finally have a real source generator for OpenAPI/Swagger.

Fastendpoints strikes me as the perfect place to do so because it's so structured with the Configuration function on the endpoints that defines the documentation etc. This approach would completely eliminate the need to run the project and thus have all of the dependencies available just to generate swagger documentation, and would enable easy generation of enums (properly) and even the new Generics support in V3.1.

And it would be a build artifact which means that it could be easily shared and no runtime generation would have to occur either. This would mean that CI/CD would get better and faster to run too.

[dj-nitehawk]

absolutely love the idea...
i just wish we had the manpower/resources to achieve something like that (we currently don't).
maybe we can start a separate project under the FastEndpoints github organization and assemble a team from the community.

team members would have to posses experience with the following:

• familiarity with FE swagger generation (configuration)
• roslyn source generators
• OAS3.1 spec

my assumption is that building/maintaining source generators is no walk in the park and is a huge undertaking, especially for something that has the potential to replace an essential pkg like nswag. so, we might have to make it a paid offering. i.e. users would have to buy a license to support the effort. i'm thinking a perpetual license where you'd get free updates for a year. the license cost would probably be around $60.

let's guage the interest of the community regarding this matter.
react to this message in the following manner:

• 🚀 would like to help build it (no monetary compensation necessary)
• 🎉 would like to help build it (monetary reward is appreciated)
• ❤️ would buy a license
• 👀 can't afford paid software
• 😆 i never pay for software

[JohnGalt1717]

I have built this the hard way in the past using annotations in controllers that dumps hard coded clients. I haven't written any source generators, but I'd be happy to help. I have written a ton of NSwag and Swashbuckle processors to fix all of the stuff that isn't supported by them in OpenApi 3.x+ so I know that standard well, and I have contributed to the Dart swagger client generator.

Also note that I discovered that there is some work being done for .net 9 with Swagger. I'm not sure what they're doing or what the outcome would be, but it would be good to sync up on what they're doing so as to not reinvent the wheel if what they're doing is a source generator. (I don't think so, but...)

[dj-nitehawk]

yes it would be best to find out what MS has planned regarding swagger generation.
btw, have you tried swagger/client generation with a msbuild task? does that not work for your "microservices" use case? where exactly does it fall short? just wondering, since i don't really deal with microservices on a regular basis in my work.

[JohnGalt1717]

So fundamentally, because all Swagger right now is based on things that are only available at runtime, the generation requires that everything be there from DI. And that means that it will almost certainly hit the database, your Redis cache and more simply by adding these things with the AddXXX methods on services. The msbuild task example just runs the compiled code and then generates the swagger from the running application. It isn't building the swagger at all persay. (This isn't unique for fast endpoints, nor nswag, Swashbuckle does it too and it's bad.)

Aspire takes those from known "there" using docker compose or similar for the developer, to transiently spun up on run of the host. As a result, if you run a micro-service by itself, they basically just fail, which means that msbuild/environment variable etc. doesn't help because it will break on run. The only way to do this with Aspire right now is to set the flag on the Host and pass it down to the services and let them all run and exit as a result of running the host.

Which is really really really ugly and runs ALL of them, not just the one you needed to update potentially breaking the others in the mean time. (because you're working on many, and the rest aren't ready to have their swagger regenned)

By creating a source generator and executing based on the code, you eliminate all of this because you're not deriving your Swagger from runtime, but from code as it should and can be (and we know this, because even Minimal APIs now has a source generator, demonstrating that it's more than possible to source generate Swagger because for Minimal APIs to be able to be source generated, you had to know everything about the endpoint.

As a result of doing this, you get:

1. Compile time swagger instead of runtime.
2. You get no dependencies for generation on your entire DI Stack.
3. You decouple yourself from Microsoft's outdated OpenAPI Stack to generate swagger.
4. You eliminate an entire step in CI/CD that is pretty costly of actually having to run your code to gen your swagger thus saving you $$$ in your Github actions (as an example)

If MS is building a source generator, then fast endpoints should lift it. It almost certainly will be minimal apis only, so it won't work for fast endpoints, putting fast endpoints at a disadvantage. But that source generator can probably be adapted so a lot of the work will be done for you.

If MS isn't building a source generator and is instead building their own version of Swashbuckle or NSwag, then fast endpoints will have a major competitive advantage because that approach is fundamentally broken with Aspire, which is the biggest thing in CS right now, I'm even getting GO and PHP devs drooling over Aspire.

[dj-nitehawk]

nicely put...
that should get the community thinking...
will personally spend some time investigating a path forward (as time permits).
cheers!

[VIOVNL]

Maybe the new OpenApi generator by MS in .Net 9 is related to this topic?

dotnet/aspnetcore#54599

Video tut: https://www.youtube.com/watch?v=8xEkVmqlr4I

[JohnGalt1717]

I chimed in.

[dj-nitehawk]

the docs say:

• Support for generating OpenAPI documents at buildtime and serializing them to disk

but that's about it, no other details of how it's done is available yet. maybe they have a source generator coming? guess we'll have to wait n see.

---

in any case, we've poured many hundreds of hours of work into making NSwag behave correctly for FE. and if we're to switch to the MS pkg, we're gonna have to spend several hundred more hours porting all that work in to the MS pkg, which is no easy task by any means.

as of now, i see no real reason to switch yet due to:

• nswag is in active development (no reason to search for alternatives, becaus FE made the right choice early on)
• nswag has a better feature set and customization options
• FE's swagger generation (via nswag) is top notch and has better devx compared to vanilla nswag/ms pkg
• there's a sense of loyalty to nswag which has been helping us all these years
• ms pkg is not mature enough yet/ feature-set seems basic
• ms pkg seems to lack proper documentation
• ms pkg will take some months/years to become the defacto choice (if it ever does)
• ms pkg has no built-in swagger ui

so yeah, i think we don't even need to think about jumping ship from nswag to ms until their pkg gives us some solid reasons to do so. if and when that happens, i'm willing to put in the the work. a source generator like the one we've discussed above would be a good enough reason to switch, if it ever comes from MS.

if on the otherhand, community members would like to start working on a FastEndpoints.OpenApi package to port the nswag code, we can get that going as a community effort, which we can eventually offer as an alternative to the FastEndpoints.Swagger package.

[MichaelHochriegl]

I've written a couple of source generators and love them, but yep, getting them behaving right can be a real pain.

So you guys would want to generate the Open API json via SG? Or also the UI?

[dj-nitehawk]

@MichaelHochriegl mainly looking to generate the swagger json by scanning the code for all the types/values most probably from EndpointSummary implementations.

[MichaelHochriegl]

Ah, I could help with the actual Source Gen part, but I have zero knowledge of the OpenAPI spec.