aspnetcore
aspnetcore copied to clipboard
dotnet
Announcement: Swashbuckle.AspNetCore is being removed in .NET 9
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.
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?
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.
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?
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.
NSwag is great, I've always deleted Swashbuckle from my projects and switched them to NSwag.
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.
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?
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.
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.
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...
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.
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 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
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 ,
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.
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 :)
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
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
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).
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.
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.
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...
@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.
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.
@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.
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.
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).
- 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.
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.
