Announcement: Swashbuckle.AspNetCore is being removed in .NET 9

[JeremyLikness]

The ASP.NET Core team began shipping web API templates with a dependency on Swashbuckle in the .NET 5 timeframe. The decision allowed the team to provide built-in support for OpenAPI, a language-agnostic, platform-neutral representation of web-based APIs that contains everything needed to discover and interact with HTTP-based service endpoints. You may be more familiar with the name “Swagger” that refers to a set of tools for working with OpenAPI documents. The information in the OpenAPI document enables scenarios like client code generation, stubbing server code, creating documentation and dynamically producing a web-based UI to interactively test the API. It also is heavily used in artificial intelligence applications to provide prompts that describe the API for use by generative AI.

Swashbuckle is a great project, and we appreciate the time and effort its owner and community contributors have put into it. The project is no longer actively maintained by its community owner. Issues have not been addressed or resolved, and there is not an official release for .NET 8. The ASP.NET Core team will provide a solution for this in the .NET 9 release. The plan is to remove the dependency on Swashbuckle.AspnetCore from the web API template and extend the capabilities introduced with Microsoft.AspNetCore.OpenApi to provide OpenAPI document generation.

There are projects other than Swashbuckle, such as NSwag, that also support OpenAPI document generation as well as client and server generation. The article ASP.NET Core web API documentation with Swagger/ OpenAPI details how to incorporate these packages into your own projects.

ASP.NET Core has evolved significantly since the 5.0 release. As early as ASP.NET Core 3.1 with the ApiExplorer, the framework supports all the metadata necessary to describe a web API. In Visual Studio, there is now built-in support for .http files along with the new Endpoints Explorer to explore, test, and debug APIs in your projects. There is also an extension available for .http file support in Visual Studio Code.

OpenAPI is an important component of the API ecosystem, and we will make it a more first-class citizen in ASP.NET Core. We will focus on the fundamental scenario of generating the OpenAPI document in JSON format in the .NET 9 timeframe and have already begun work. In fact, you can weigh-in on our design and help us prioritize the right features by engaging with the tracking issue.

[Lionhunter3k]

Why not contribute to swashbuckle? Instead of creating from scratch?

[GabrielHSFerreira]

Why not contribute to swashbuckle? Instead of creating from scratch?

I thought the same. Isn't that the fastest way to evolve and provide support for the framework new versions? Or is Swashbuckle repo so abandoned that the owner wouldn't even review proposed PRs?

[DemoBytom]

I thought the same. Isn't that the fastest way to evolve and provide support for the framework new versions? Or is Swashbuckle repo so abandoned that the owner wouldn't even review proposed PRs?

There are currently 68 opened pull requests there, dating back to 2020, and the last merged PR was in November 2022.

[GabrielHSFerreira]

I thought the same. Isn't that the fastest way to evolve and provide support for the framework new versions? Or is Swashbuckle repo so abandoned that the owner wouldn't even review proposed PRs?

There are currently 68 opened pull requests there, dating back to 2020, and the last merged PR was in November 2022.

That's a shame. In that case, I couldn't agree more with the decision/strategy. Does anyone know if the repo owner is fine?

[JeremyLikness]

I thought the same. Isn't that the fastest way to evolve and provide support for the framework new versions? Or is Swashbuckle repo so abandoned that the owner wouldn't even review proposed PRs?

There are currently 68 opened pull requests there, dating back to 2020, and the last merged PR was in November 2022.

That's a shame. In that case, I couldn't agree more with the decision/strategy. Does anyone know if the repo owner is fine?

We reached out and spoke with the owner to understand our options and see if there was a way to help. As far as I know, he (Richie) is fine and actively looking for someone willing to take over the repo. If you or anyone you know is interested, I encourage you to reach out. I also spoke with NSwag's owner to give him a heads up about our decision and so he can weigh in on our techincal design discussion.

Why not contribute to swashbuckle? Instead of creating from scratch?

Great questions, thank you. We have contributed in the past. Fortunately, we also are not starting from scratch, as we have already built and extended the libraries that hold the metadata. We have also investigated the document generation approach but stopped short of building it into the product. We should be able to provide more expeditious responses to feature requests or issues by owning the deliverable as opposed to having to coordinate, wait, merge, etc. The design issue covers a lot more details on what' planned and is a great place to add anything you might want to see.

[phatboyg]

NSwag is great, I've always deleted Swashbuckle from my projects and switched them to NSwag.

[TeddyAlbina]

Why not contribute to swashbuckle? Instead of creating from scratch?

Because Microsoft already have its own stuff to maintain 🤷. Also Microsoft library for OpenApi exists for years now and works well.

[RicoSuter]

Hi.

I’m the main author of the popular libraries NSwag (OpenAPI generator) and NJsonSchema (JSON Schema generator). NSwag is built on top of NJsonSchema and both libraries are quite feature rich. I dont see how Microsoft will reimplement all these features soon, but as a maintainer I’m now in the position to maintain libraries which I know will eventually be replaced (not very motivating).

At this time, I’m not sure whether it makes sense to invest a lot more in these libs and try to compete with Microsoft..

I’m just a bit worried that the feature set will never match NSwag’s and the fullstack experience (from api to client code) will eventually be worse because it’s not one “full-stack” toolchain (sample feature: polymorphic schemas).

What do you think?

[snickler]

At this time, I’m not sure whether it makes sense to invest a lot more in these libs and try to compete with Microsoft..

It's always important to provide an alternative. If you know that you're providing more, keep providing it.

[edarruiz]

It's kinda sad because we are used to it, but I understand and support the decision, it's perfect reasonable. Even if you will not provide all the features we are used on the first iterations, it's fair to believe that over the time and with the new releases, more and more features should become available for the developers without any external dependency.

Personally, I think this decision has even more hidden basis and details attached to it, since probably their process of packaging the deliveries that depends on 3rd party libraries could have a negative impact on their ship schedule, security considerations and quality dependency, which give us even more reasons to support their decision.

[RicoSuter]

It's kinda sad because we are used to it, but I understand and support the decision, it's perfect reasonable. Even if you will not provide all the features we are used on the first iterations, it's fair to believe that over the time and with the new releases, more and more features should become available for the developers without any external dependency.

I agree, in the long term it makes sense that Microsoft owns the library with the OpenAPI and JSON Schema models and also the ASP.NET generators as it has to be fully in sync with the runtime... I just hope there will be rich extension points (schema, operation and document filters/processors) so that we can easily provide additional functionality in a nice way...

[captainsafia]

I just hope there will be rich extension points (schema, operation and document filters/processors) so that we can easily provide additional functionality in a nice way...

Customizability of the generated document is tracked under the P1 tasks there. I've posted some thoughts on the current state of this under the "Customizing document generation" heading in the linked document. This is an area I'm hoping we can do special API/design focus on once the foundational work of getting the OpenAPI document generated is done.

[edandersen]

Swashbuckle and NSwag were extremely important for enabling the generation of JS/TS clients from WebAPI backend code. Please don't break that workflow.

[kant2002]

I thought the same. Isn't that the fastest way to evolve and provide support for the framework new versions? Or is Swashbuckle repo so abandoned that the owner wouldn't even review proposed PRs?

There are currently 68 opened pull requests there, dating back to 2020, and the last merged PR was in November 2022.

That's a shame. In that case, I couldn't agree more with the decision/strategy. Does anyone know if the repo owner is fine?

We reached out and spoke with the owner to understand our options and see if there was a way to help. As far as I know, he (Richie) is fine and actively looking for someone willing to take over the repo. If you or anyone you know is interested, I encourage you to reach out. I also spoke with NSwag's owner to give him a heads up about our decision and so he can weigh in on our techincal design discussion.

I did not find a way connect to Richie, so I create issue https://github.com/domaindrivendev/Swashbuckle.AspNetCore/issues/2773 so he can tell his opinion on project continuation. If there other way to connect with him better, please let me know. Others probably also welcomed to try that route

[darren-clark]

Swashbuckle and NSwag were extremely important for enabling the generation of JS/TS clients from WebAPI backend code. Please don't break that workflow.

I don't think anyone is breaking that, but providing a Microsoft provided alternative. Which I agree would be absolutely demotivating if I were @RicoSuter ,

[sherviniv]

Swashbuckle is not working correctly with the minimal API. On .Net 8 I was surprised why still the default .Net 8 projects using Swashbuckle. Although I like Swashbuckle, it is time to update it or use an alternative one like Nswag.

[1plam]

The reasoning is totally understandable, and I'd say it's a right decision to consider. There are some alternatives nowadays, as mentioned in the announcement, like NSwag.

Not going to lie, it's great to see the ASP.NET Core team taking ownership of this pretty much important aspect. Generating the OpenAPI document in JSON format seems like a solid starting point for .NET 9, and it's good to see that work has already begun. I'm looking forward to seeing how the built-in OpenAPI support in ASP.NET Core progresses.

Kudos to the Swashbuckle team for their contributions over the years :)

[christianhelle]

I'm a huge fan of OpenAPI and built tooling on top of it for various purposes. I use SwaggerUI less and less mostly because it doesn't perform very well with large payloads so I have switched almost entirely to .http files. I built a tool called HTTP File Generator that takes an OpenAPI document and generates .http files per endpoint, this tool is built on top of @RicoSuter's NSwag, which I think is the best parser of OpenAPI documents

A request from me would be to make it possible for the build process to produce OpenAPI specification files as part of the build output out-of-the-box without me having to do MSBuild magic that starts the app, downloads the OAS document, then shuts down the app again

[christianhelle]

I’m the main author of the popular libraries NSwag (OpenAPI generator) and NJsonSchema (JSON Schema generator). NSwag is built on top of NJsonSchema and both libraries are quite feature rich. I dont see how Microsoft will reimplement all these features soon, but as a maintainer I’m now in the position to maintain libraries which I know will eventually be replaced (not very motivating).

@RicoSuter I'm a big fan of your work and I hope you continue to maintain NSwag with the same high-quality that it always had

[mhkolk]

It's kinda sad because we are used to it, but I understand and support the decision, it's perfect reasonable. Even if you will not provide all the features we are used on the first iterations, it's fair to believe that over the time and with the new releases, more and more features should become available for the developers without any external dependency.

I agree, in the long term it makes sense that Microsoft owns the library with the OpenAPI and JSON Schema models and also the ASP.NET generators as it has to be fully in sync with the runtime... I just hope there will be rich extension points (schema, operation and document filters/processors) so that we can easily provide additional functionality in a nice way...

From what I've seen over the years (decades) with MS is they will provide a built-in alternative but it will lack many useful features, most often it is just something quickly cobbled together just to say we have our own solution for this and that happens so often with them.

What I'd say is don't stop working, on the contrary, go all-in and offer paid products with support and clear roadmap, which serious companies really need.

When I was tired rewritting auth and login for the 16th time when I was using ASP.NET Identity we went with Auth0, paid their plan and have been happily using their service for many years now (without constant rewrites and deprecations).

[adrianteixeira]

Hi.

I’m the main author of the popular libraries NSwag (OpenAPI generator) and NJsonSchema (JSON Schema generator). NSwag is built on top of NJsonSchema and both libraries are quite feature rich. I dont see how Microsoft will reimplement all these features soon, but as a maintainer I’m now in the position to maintain libraries which I know will eventually be replaced (not very motivating).

At this time, I’m not sure whether it makes sense to invest a lot more in these libs and try to compete with Microsoft..

I’m just a bit worried that the feature set will newer match NSwag’s and the fullstack experience (from api to client code) will eventually be worse because it’s not one “full-stack” toolchain (sample feature: polymorphic schemas).

What do you think?

Thank's for create the NSwag, Rico. Be sure that helped so many developer's, like me, and gave your contribuition to .NET comunity.

Using the NewtonSoft lib as example, Microsoft used to reconstruct the best's libs to enable the built-in feature. The core team dont want use other dependencies instead built-in MS. In my vision, they have to gave the credit's of original lib for author's.

[julealgon]

I’m just a bit worried that the feature set will newer match NSwag’s and the fullstack experience (from api to client code) will eventually be worse because it’s not one “full-stack” toolchain (sample feature: polymorphic schemas).

What do you think?

@RicoSuter , kiota is vastly superior to NSwag in terms of client generation already. We were basically forced to switch to kiota with a new dependency we added recently because NSwag would just flat out fail to generate the client for its OpenAPI spec, while kiota handled it gracefully.

So I disagree with you that "the feature set will never match": in some areas it already surpasses NSwag handily.

---

@edandersen Swashbuckle and NSwag were extremely important for enabling the generation of JS/TS clients from WebAPI backend code. Please don't break that workflow.

Consider switching to kiota right now. It is considerably more robust than NSwag in our experience at least in terms of C# clients. It also generates TS clients so I'd recommend looking into it for your use case.

---

@christianhelle ...built a tool called HTTP File Generator that takes an OpenAPI document and generates .http files per endpoint, this tool is built on top of @RicoSuter's NSwag, which I think is the best parser of OpenAPI documents

See above. NSwag is quite fragile for that based on our recent experience.

[RicoSuter]

So I disagree with you that "the feature set will never match": in some areas it already surpasses NSwag handily.

I was more talking about the OpenAPI generation and not code generation (as this is not part of this feature here)... of course if MS can provide all features and support all funny and strange OpenAPI edge cases I would be very glad...

[julealgon]

@RicoSuter

So I disagree with you that "the feature set will never match": in some areas it already surpasses NSwag handily.

I was more talking about the OpenAPI generation and not code generation (as this is not part of this feature here)...

Well you did explicitly mention

...the fullstack experience (from api to client code)...

Though. That's precisely the point I was arguing against. If you focus on just the OpenAPI document generation, then fair enough.

Unless you just meant "the client code for the test/documentation UI"? In that case, fair enough.

[DemoBytom]

Using the NewtonSoft lib as example, Microsoft used to reconstruct the best's libs to enable the built-in feature. The core team dont want use other dependencies instead built-in MS. In my vision, they have to gave the credit's of original lib for author's.

Microsoft switchted to their own implementation, because they needed an allocation free json serializer for Kestrel/Asp .Net Core, for performance reasons. And the required optimizations were not possible to introduce into Newtonsoft.Json without a total rewrite, on top of reducing functionality, that wouldn't be possible with the strict performance requirements.

On top of that James Newton-King, the creator of Newtosoft, joined Microsoft a while back, and to my knowledge, advised on the System.Text.Json design.

[julealgon]

@adrianteixeira Using the NewtonSoft lib as example, Microsoft used to reconstruct the best's libs to enable the built-in feature. The core team dont want use other dependencies instead built-in MS. In my vision, they have to gave the credit's of original lib for author's.

They didn't build System.Text.Json based on Newtonsoft.Json. STJ is considerably more optimized for performance compared to Newtonsoft. It makes no sense "giving credit to the author" of a completely different library.

The same situation will likely happen here, as Microsoft is very performance-focused in the last years.

Additionally, Microsoft did hire James Newton-King, the author of Newtonsoft.Json anyways.

[captainsafia]

A request from me would be to make it possible for the build process to produce OpenAPI specification files as part of the build output out-of-the-box without me having to do MSBuild magic that starts the app, downloads the OAS document, then shuts down the app again

@christianhelle The later part of this is really hard to execute on. I did some experimentation a while back to develop a source-generator based OpenAPI generator. Two hiccups with this approach:

• Source generators currently only support outputting source files back into the compilation. They don't have functionality to output non-source files out to a different location. There's an ongoing proposal to rectify this so this might not be a problem soon.
• Static analysis won't catch all of the details that reflection would, so the document that is generated will have lower fidelity than what you would get at runtime. You'll end up having to fill some details (groups, argument sources) at compile time. There's also the fact that it's a considerable amount of engineering work to do everything we currently do with reflection using static analysis.

Outside of using source generation and static analysis, I haven't formed any ideas as to how to solve this problem. If there's some other obvious solution I hadn't considered, let me know, but this one is definitely a tough one to solve. 😅

In the long run, MS doesn't want you to use other dependencies except MS.

Not true here! One of my main goals with this work is to make sure that we are able to generate a high-quality OpenAPI document out-of-the-box that can be plugged into the ecosystem of tooling that already exists in the ecosystem. I've outlined some of the tools I want to make sure integrate well in the design issue (https://github.com/dotnet/aspnetcore/issues/54598). If you have thoughts on other tools we should test integrations with, let me know.

[terrajobst]

Using the NewtonSoft lib as example, Microsoft used to reconstruct the best's libs to enable the built-in feature. The core team dont want use other dependencies instead built-in MS. In my vision, they have to gave the credit's of original lib for author's.

I was involved with this and we specifically did. We heavily worked with the author of Newtonsoft.Json (@JamesNK).

[christianhelle]

• Source generators currently only support outputting source files back into the compilation. They don't have functionality to output non-source files out to a different location. There's an ongoing proposal to rectify this so this might not be a problem soon.

@captainsafia It's not exactly the best practice, but source generators can do whatever they want. I have previously (mis)used source generators for producing files on disk and not just back into the compilation.

[tjementum]

A request from me would be to make it possible for the build process to produce OpenAPI specification files as part of the build output out-of-the-box without me having to do MSBuild magic that starts the app, downloads the OAS document, then shuts down the app again

I would like to second this request from @christianhelle. We are currently outputting the swagger.json contract as part of a post build step (using NSwag), that is in turn used to generate a strongly typed TypeScript definition for our SPA. Since this needs to start the .NET WebAPI and execute code to extract the contract, this is extremely slow - the build went from 1-2 seconds to ~10 seconds, on a fairly simple solution.

Also, this is very error prone, if I have an exception in the startup while developing the build fails when generating the swagger contract, which often gives a very misleading exception.

There's also the fact that it's a considerable amount of engineering work to do everything we currently do with reflection using static analysis.

@captainsafia I know it can be hard. In my previous job, we built our own TypeScript generator that ran as part of the build. It took 200 ms, on a fairly big API. We of course only supported the edge cases we needed (but over the course of 5 years and a dozen teams, it became fairly complete), but you being Microsoft, this is exactly where you can add the engineering power and extension points that others cannot. But 200 ms vs 10 seconds on every build is worth a big effort.

So here is a huge vote for making this at compile time.

[RicoSuter]

I would like to second this request from @christianhelle. We are currently outputting the swagger.json contract as part of a post build step (using NSwag), that is in turn used to generate a strongly typed TypeScript definition for our SPA. Since this needs to start the .NET WebAPI and execute code to extract the contract, this is extremely slow - the build went from 1-2 seconds to ~10 seconds, on a fairly simple solution.

I dont see how you could change that with the current architecture: You need to run the app's DI and at least set up the HTTP/request processing pipeline (e.g. call MapGet(...) so that the metadata is registered) as this generates the metadata (API explorer and System.Text.Json's type resolver) needed to generate the OpenAPI document. That's also why source generators will not work as they only have access to static/compile resources but must not actually start the application.

[tjementum]

I dont see how you could change that with the current architecture...

Luckily, I'm not limiting my thinking based on the current architecture 😄.

But again, in my previous job, we built a compile time TypeScript contract from our .NET API (~200 ms overhead). This is what I'm using NSwag for on my new project, but it's taking ~10 seconds.

I believe we used reflection to look at the WebAPI assembly. As far as I know, the TypeScript contract contained everything that was in the Swagger API, including types, polymorphism, documentation, etc.

I don't understand why reflection is not enough to build a complete contract. You mention that you need to call MapGet() to get metadata, but we were able to extract all that using reflection. I'm sure you have some edge cases, but with 200 ms vs 10 seconds on every compile, I'm willing to live with what is possible with a static contract.

[captainsafia]

I don't understand why reflection is not enough to build a complete contract.

Yep, this is precisely the point. Reflection is what you need in order to be able to generate a complete model of the app. Reflection needs to happen at runtime, which means that some assembly has to be executing in order for the reflection APIs to be invoked and the appropriate metadata to be populated.

The reason compile-time generation needs to launch the running app is so that the dynamic analysis code that happens via reflection at runtime can execute.

You need to run the app's DI and at least set up the HTTP/request processing pipeline (e.g. call MapGet(...) so that the metadata is registered) as this generates the metadata (API explorer and System.Text.Json's type resolver) needed to generate the OpenAPI document. That's also why source generators will not work as they only have access to static/compile resources but must not actually start the application.

WRT to @RicoSuter's point here, it is possible to introspect some things with static analysis happening in a source generator. The Request Delegate Generator for minimal APIs we shipped in .NET 8 does much of the same static analysis that an OpenAPI source generator would need to do.

The gotcha is with certain things, like endpoint metadata, which need to be run via an executing app in order to be correctly processed. You won't be able to "see" those with static analysis in generator so you'll get OpenAPI files that are not accurate in some cases.

The other gotcha is that we have no source generator for MVC-based apps to show prior art around statically analyzing controllers/actions.

So, yes, the TLDR is that reflection provides the most accuracy when generating a model for the application and it needs to happen within the context of a running app.

but with 200 ms vs 10 seconds on every compile, I'm willing to live with what is possible with a static contract.

With all that being said, I think we can solve the problem of the OpenAPI document generation contributing so much to the build in other ways. I'd be curious to get a sense of what the binlogs for your compilation would show. If you are able to file an issue with the bin log or some screenshots of it, that would be helpful.

@captainsafia It's not exactly the best practice, but source generators can do whatever they want. I have previously (mis)used source generators for producing files on disk and not just back into the compilation.

@christianhelle Yeah, unfortunately, writing to disk via generators in this way can be risky and is not something we'd be able to take advantage of in a generator shipped as part of ASP.NET Core. The proposed artifacts model I mentioned early provides a much saner strategy for doing this (once it exists).

[toralux]

I thought the same. Isn't that the fastest way to evolve and provide support for the framework new versions? Or is Swashbuckle repo so abandoned that the owner wouldn't even review proposed PRs?

There are currently 68 opened pull requests there, dating back to 2020, and the last merged PR was in November 2022.

There is a quite new fork https://github.com/Havunen/DotSwashbuckle that has merged many pull requests from Swashbuckle and fixed a lot of the long-outstanding issues in the not-very-well-maintained Swashbuckle project.

[mesMess]

Hello All, just a heads up as Richie is finalizing a small group of individuals to help divvy up the tasks for Swashbuckle. We'll be meeting next week to look at knowledge transfer, roadmap, etc. moving forward.

[namtab00]

Reflection needs to happen at runtime, which means that some assembly has to be executing in order for the reflection APIs to be invoked and the appropriate metadata to be populated.

It most definitely needs to happen at runtime.

A modular application, which exposes different sets of endpoints (based on active modules, env or DB config) must produce an OpenAPI spec that describes the precise active subset of endpoints.

Static analysis would describe all endpoints present in sources, regardless of real runtime availability.

[bachratyg]

I don't understand why reflection is not enough to build a complete contract. You mention that you need to call MapGet() to get metadata, but we were able to extract all that using reflection. I'm sure you have some edge cases, but with 200 ms vs 10 seconds on every compile, I'm willing to live with what is possible with a static contract.

The moment you have a custom json converter or any extension that dynamically alters the api shape you either have to run (or interpret) the actual code or have some 'oracle' to get reliable results. This is really unfortunate (also has security implications) but not a unique problem e.g. Entity Framework Core's migration generation suffers from the same issue. It's not a silver bullet but setting up a dedicated configuration environment for contract gen and conditionally excluding problematic services helps getting a faster startup time.

[RihanArfan]

If there's going to be web viewer, I would love to see Scalar used instead of (or alongside but as the default) Swagger UI, which has a really dated UI and eh UX. Many other frameworks have support for it (some officially too like Nuxt), and it'd be amazing if .NET could too here.

I've just seen the tracking issue https://github.com/dotnet/aspnetcore/issues/54598, where it was mentioned that there's no official plans for supporting a UI anymore.

• https://scalar.com/ (quick tldr)
• https://github.com/scalar/scalar (docs, install)
• https://docs.scalar.com/swagger-editor (demo, click "Show Example" on the right, then "Preview" on the top)

Implementation would be as simple as an index.html file that loads Scalar from the CDN and passes the URL to the OpenAPI spec. A default custom theme can also be applied (such as .NET's purple, like Nuxt's official integration which has their colour theme).

---

[captainsafia]

@RihanArfan Thanks for sharing Scalar with the thread! It looks pretty nifty.

We're still not planning on adding a default UI out of the box in the Microsoft.AspNetCore.OpenAPI package. However, we're documenting ways to integrate with various UIs in our docs.

I took a look at Scalar's docs and it looks like the connecting ASP.NET Core's built-in doc should be pretty straightforward. I can look into documenting this in our docs.

[marclave]

hey @captainsafia @RihanArfan ! thanks for the kind words! So cool to see the docs live!

please let me know if there are improvements/feature requests we can ship to improve Scalar :)

[dmitry-pavlov]

Makes total sense to me. No need to keep it dependent on Swashbuckle.AspNetCore as developers should choose deps themselves. I use NSwag for many years and happy with that, as Swashbuckle usually doesn't cover my needs.

The only thing for framework - the interfaces should be clearly defined and used by the framework, so implementations can realy rely on implementing intefaces will make it working everywhere, Also please pay attention to custom extensions we all need, so we can adjust what's needed easily (without a need to rip the guts out of framework weird ways)

[aukgit]

I think it is best to remove after the UI is ready to integrate.

[julealgon]

Any idea on how api versions (w minimal apis) will work with scalar ? Ideally, if I have an endpoint that supports 2 versions and mentions that one is deprecated I'd like to see that in scalar.

@orosbogdan you should consider moving Scalar-specific discussions to the Scalar repo.

[JacquesGariepy]

will you base yourself on that? https://learn.microsoft.com/en-us/dotnet/api/microsoft.openapi.writers

[jusbuc2k]

Hi.

I’m the main author of the popular libraries NSwag (OpenAPI generator) and NJsonSchema (JSON Schema generator). NSwag is built on top of NJsonSchema and both libraries are quite feature rich. I dont see how Microsoft will reimplement all these features soon, but as a maintainer I’m now in the position to maintain libraries which I know will eventually be replaced (not very motivating).

At this time, I’m not sure whether it makes sense to invest a lot more in these libs and try to compete with Microsoft..

I’m just a bit worried that the feature set will never match NSwag’s and the fullstack experience (from api to client code) will eventually be worse because it’s not one “full-stack” toolchain (sample feature: polymorphic schemas).

What do you think?

I can understand the complexity that goes into MS deciding to include or even recommend a third party library for the "in the box" experience for aspnet, so I don't really know what's better, but, I 100% agree with @RicoSuter. This will be like System.Text.Json, which is great, but on the first release was really limited, and still to this day does not have all the features of Newtonsoft, years and years later.

[bkoelman]

Hi. I’m the main author of the popular libraries NSwag (OpenAPI generator) and NJsonSchema (JSON Schema generator). NSwag is built on top of NJsonSchema and both libraries are quite feature rich. I dont see how Microsoft will reimplement all these features soon, but as a maintainer I’m now in the position to maintain libraries which I know will eventually be replaced (not very motivating). At this time, I’m not sure whether it makes sense to invest a lot more in these libs and try to compete with Microsoft.. I’m just a bit worried that the feature set will never match NSwag’s and the fullstack experience (from api to client code) will eventually be worse because it’s not one “full-stack” toolchain (sample feature: polymorphic schemas). What do you think?

I can understand the complexity that goes into MS deciding to include or even recommend a third party library for the "in the box" experience for aspnet, so I don't really know what's better, but, I 100% agree with @RicoSuter. This will be like System.Text.Json, which is great, but on the first release was really limited, and still to this day does not have all the features of Newtonsoft, years and years later.

I recognize your sentiment. I've had my own share of issues with STJ, and even today I sometimes choose Newtonsoft.Json for new projects because of missing features. But I think the OpenAPI space is quite different. At the time, Newtonsoft was a maintained product that worked great. That's not to say for OpenAPI. NSwag is basically dead, because key issues, such as this and this, aren't being addressed. Swashbuckle was dead for a year, but fortunately got revived after this announcement. Kiota (not an official Microsoft product and highly understaffed) is a disaster (1, 2, 3).

Sure, it will take a few years before these new projects mature to the level we can actually use them and the needed extensibility points are in place. But at least they're trying to revive an ecosystem that's barely usable today.

[julealgon]

@bkoelman

Kiota (not an official Microsoft product and highly understaffed) is a disaster (1, 2, 3).

Where did you get the idea that Kiota is not a Microsoft product? It's a repo in Microsoft's org in github.

Also, "a disaster"? It is a fairly new project and extremely actively developed, there are updates all the time. Why do you consider that a disaster because of 3 issues, one of which that is completed and another closed?

[bkoelman]

Just read the threads, its their own words.

[julealgon]

Just read the threads, its their own words.

Just went through them and honestly... all I see is your opinion, with which I respectfully disagree: I think Kiota is really high quality compared to other solutions such as NSwag and Swashbuckle not only in terms of overall design, but also performance-wise, and we've been using it in production scenarios successfully with a couple minor workarounds in a few cases for corner scenarios it doesn't yet have support for.

Additionally, nowhere in those threads it's stated it is not a Microsoft-owned product, so I still fail to see where you got that from.

[bkoelman]

Part of it is at https://github.com/microsoft/kiota/issues/4349#issuecomment-2007457753, https://github.com/microsoft/kiota/issues/4349#issuecomment-2009529813 and https://github.com/microsoft/kiota/issues/4349#issuecomment-2007302190. It's not stated literally, but reading between the lines indicates the project isn't being taken very seriously internally; it's merely a few enthusiastic employees who struggle with getting time to work on it.

As for quality: I suppose it depends on needs and expectations. I've tried to port our existing NSwag tests to kiota, which was quite a pain. These tests just cover the basics, not real-world projects concerned with deployment, versioning, logging, error handling, cross-platform, extensibility, etc. Don't be misled by issues getting closed as completed: they typically don't test with the provided repro steps, leaving it in a broken state. And because of poor test coverage, our code often breaks with new releases. I'm getting tired of being their beta tester. If NSwag would still take fixes, I'd likely abandon kiota.