Announcement: Swashbuckle.AspNetCore is being removed in .NET 9 #54599
Comments
JeremyLikness
added
area-mvc
|
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? |
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. |
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.
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. |
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? |
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. |
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... |
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 did not find a way connect to Richie, so I create issue domaindrivendev/Swashbuckle.AspNetCore#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 |
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 |
@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 |
|
I've just seen the tracking issue #54598, where it was mentioned that there's no official plans for supporting a UI anymore.
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). |
|
@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. |
|
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 :) |
|
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) |
|
I think it is best to remove after the UI is ready to integrate. |
@orosbogdan you should consider moving Scalar-specific discussions to the Scalar repo. |
|
will you base yourself on that? https://learn.microsoft.com/en-us/dotnet/api/microsoft.openapi.writers |
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. |
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? |
|
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. |
|
Part of it is at microsoft/kiota#4349 (comment), microsoft/kiota#4349 (comment) and microsoft/kiota#4349 (comment). 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. |
NIH |
Just FYI: You can override templates on your side without any changes in NSwag (1)... The big problem is that these bigger PRs often broke other peoples code because they were not well tested etc. so I'm a bit hesitant to just merge them - because in the end I'm the one who gets the blame and has to fix everything... |
I should probably try and help to clarify here considering it is my words that are being interpreted here. It was my intent to convey that Kiota wasn't created because Microsoft, as an organization, had a business need to go build an OSS API client code generator. It was built because one team, in one corner of Microsoft, had a need for a multi-language client code generator based on OpenAPI and nothing existed that met their requirements. However, we didn't want to build yet another client code generator that was tightly coupled to a specific API or set of APIs. Does Kiota need a lot more work? yes. Is it understaffed? I'm sure most teams at Microsoft feel this way. The funding is for building Microsoft Graph SDKs. We are stretching that to try and enable building SDKs for any API. This is why we regularly ask for community contributions for fixes and enhancements. Is it a disaster? I don't think so. A number of companies have done comparative analysis of other products out there and decided that Kiota is a viable option (e.g. GitHub, RedHat). NSwag have been in the business of generating SDKs for .NET and TypeSpec for far longer than we have. I expect there are many things it does better than we do currently. I hope we can continue to improve Kiota to produce at minimum an equivalent experience. As the Kiota team, we are trying to be as honest as possible about why Microsoft employees are investing in building this tooling. It makes it harder for us to do this when these words are turned into criticisms as "not official" or "isn't taken very seriously". From experience, I can say that being "official" is not always the blessing you might think it is. Personally, I would rather Kiota be a 100% community driven effort. I just do not see a way to make that happen today. The .NET community has not been very successful at creating OSS projects without either hero contributors that have alternate income sources or corporate sponsorship. Our hope is that we continue to steer Kiota in a way that allows Microsoft to justify funding, whilst allowing as much community direction as possible that is inline with the stated objectives of the project. As a footnote, the OpenAPI.Net library that Swashbuckle uses was also not an "official" Microsoft project. It was a personal project https://github.com/tavis-software/Tavis.OpenApi that I convinced several Microsoft teams to contribute to and evolve. 8 years later it is now a key piece of infrastructure across Microsoft products. The same team that build Kiota, also maintain that library. Not every Microsoft project takes the "standard" path. |
|
In the recent release of https://github.com/openai/openai-dotnet I noticed another generator and the use of System.ClientModel. Is this something else that Microsoft is developing together with Kiota? |
|
@HavenDV I believe that is the Dataplane generator flavour of AutoREST https://github.com/Azure/autorest.csharp/blob/feature/v3/docs/protocol_method_client.md |
|
@darrelmiller it would be indirectly related in the sense that |
|
@julealgon There has been no statement that Kiota is superseeding AutoREST. The Azure DevX team have been optimizing AutoREST to work with doing code generation from TypeSpec. Kiota remains focused firmly on generating from standard OpenAPI descriptions. |
|
@darrelmiller the comment here makes it pretty clear to me that kiota is flat out a superior product. Maybe I misinterpreted it?
It gets explicitly mentioned in that thread that kiota is not a replacement but an alternative. Honestly, based on the above alone, I personally don't get that decision. Why maintain 2 tools that perform the same job when one of them performs it better/has less limitations/less issues? Perhaps it should at least supersede AutoREST for OpenAPI-based wrappers? But anyways, I digress. |
|
@julealgon did you ever attempt to customize AutoRest? Even fltrivial stuff become complicated. Some of AutoRet list decision seems to be affected that it is used also for generation of internal Azure client for their services. |
We almost standardized on it, but learned about kiota right after and switched to that before we had the first real need to generate another proxy for one of our services. We had been using the standard connected service integration in VS which relies on NSwag up to that point, but NSwag just failed miserably when we tried using it to generate a Twilio SendGrid API client, and that's when we dropped it. I wasn't aware of that inflexibility of AutoREST, no. As a consumer, I was just making the point that I wish Microsoft would focus on a single tool (at least for OpenAPI) instead of still supporting and promoting AutoREST. |
and others
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.AspnetCorefrom the web API template and extend the capabilities introduced withMicrosoft.AspNetCore.OpenApito 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.
The text was updated successfully, but these errors were encountered: