Announcement: Swashbuckle.AspNetCore is being removed in .NET 9 #58103
Replies: 74 comments 22 replies
-
|
Why not contribute to swashbuckle? Instead of creating from scratch? |
Beta Was this translation helpful? Give feedback.
-
|
Or fork swashbuckle and maintain the fork. |
Beta Was this translation helpful? Give feedback.
-
|
Swashbuckle is maintained again but would not be easily possible to make AOT compatible without a rewrite. |
Beta Was this translation helpful? Give feedback.
-
Oh, it sounds like a reason for MS own implementation. |
Beta Was this translation helpful? Give feedback.
-
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? |
Beta Was this translation helpful? Give feedback.
-
There are currently 68 opened pull requests there, dating back to 2020, and the last merged PR was in November 2022. |
Beta Was this translation helpful? Give feedback.
-
That's a shame. In that case, I couldn't agree more with the decision/strategy. |
Beta Was this translation helpful? Give feedback.
-
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. |
Beta Was this translation helpful? Give feedback.
-
|
NSwag is great, I've always deleted Swashbuckle from my projects and switched them to NSwag. |
Beta Was this translation helpful? Give feedback.
-
Because Microsoft already have its own stuff to maintain 🤷. Also Microsoft library for OpenApi exists for years now and works well. |
Beta Was this translation helpful? Give feedback.
-
|
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? |
Beta Was this translation helpful? Give feedback.
-
|
Based on how |
Beta Was this translation helpful? Give feedback.
-
It's always important to provide an alternative. If you know that you're providing more, keep providing it. |
Beta Was this translation helpful? Give feedback.
-
|
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. |
Beta Was this translation helpful? Give feedback.
-
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... |
Beta Was this translation helpful? Give feedback.
-
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. |
Beta Was this translation helpful? Give feedback.
-
|
Swashbuckle and NSwag were extremely important for enabling the generation of JS/TS clients from WebAPI backend code. Please don't break that workflow. |
Beta Was this translation helpful? Give feedback.
-
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 |
Beta Was this translation helpful? Give feedback.
-
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 , |
Beta Was this translation helpful? Give feedback.
-
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. |
Beta Was this translation helpful? Give feedback.
-
|
As a developer point of view, I would say to Microsoft that the key here is to start a new Web API project and not have to bother with bells and whistles in order to have a web page test targeting the actions in the API. Right now, I just start a new project and BANG, I'm up and running to test my API and offer a great portal to those that will use the API. The simplicity is the key and I'm afraid that this is what we'll lose here with all this. I don't see myself going in Nuget, and then in Program.cs etc to just make sure I got something similar to what we have right now ! I hope people understand my point of fire ! Swagger page is actually nice. I don't think that the .NET 9 template is as friendly as that am I right ? |
Beta Was this translation helpful? Give feedback.
-
|
Hey, what about that domaindrivendev/Swashbuckle.AspNetCore#2778 . The owner post a message in April to say that the project will try to take a new breath with new core team. They also have released a new version, 6.6.X with .net 8 support and many fix/upgrade. On my own, I've build a new project with MS OpenAPI package, but it's way less well documented and the JSON file generation is a really mess, need to search for hours to know how to customise it because it depend of another cli (get-document) (can't rename the file without project name !) comparing to SwashBuckle.AspNetCore.Cli |
Beta Was this translation helpful? Give feedback.
-
|
Any plans for generating openAPI.json (or yaml) out of DLL in post-built or CI/CD process with a CLI or similar? Swashbuckle CLI can do this. I'm not sure if Nswag can. |
Beta Was this translation helpful? Give feedback.
-
|
@diegosasw Personnaly, I use the Microsoft.AspNetCore.OpenApi package from .net team in .net9 (in preview for the moment). You can make it build .json file in post build (it call the CLI) or buid with CLI directly. It's a little bit more complexe to use instead of Swashbuckle but after some time trying, I've got the same result. PS: I've made a PR to add option to name the file as we want. |
Beta Was this translation helpful? Give feedback.
-
|
@JeremyLikness Can't Microsoft just directly hire people to maintain these OSS projects which are extremely important for .NET? It won't be an issue to find people for that. |
Beta Was this translation helpful? Give feedback.
-
|
After NSwag pissing on my parade with it's lack of support for |
Beta Was this translation helpful? Give feedback.
-
|
I'm going to move this issue over to discussions now that we have an Announcements category there. |
Beta Was this translation helpful? Give feedback.
-
|
Stupid question of the day: Will existing Swagger pages continue to work? |
Beta Was this translation helpful? Give feedback.
-
|
Yes, if you don't make any code changes to your application things should continue to work as usual. |
Beta Was this translation helpful? Give feedback.
-
|
@captainsafia Since the new OpenApi packages don't have a UI, the templates should still ship with Swashbuckle.AspNetCore.SwaggerUI, which does also work with the new OpenApi packages as it has no dependency on the other Swashbuckle packages. Without a UI being there by default that shows up when pressing F5 it would be a huge downgrade for the templates. |
Beta Was this translation helpful? Give feedback.
-
|
Without an out of the box template API testing UI from either Swagger or something else (Aspire?), wired up to the new OpenApi packages, this is a huge regression in .NET 9 / ASP.NET Core 9 compared to templates in .NET 8. The industry is moving towards batteries-included frameworks (Laravel, Django, the Rails renaissance) for new projects and .NET appears to be moving backwards. The templates and the out of the box experience is the most important part for gaining adoption. I care deeply (probably too much) about the future of .NET and I'm worried by the direction. This is a similar story to the removal of Identity Server from the templates - throw money at the problem. You are the biggest company in the world. |
Beta Was this translation helpful? Give feedback.
-
|
I try very hard not to criticize Microsoft's development tools evolution
but this seems like a regression. If I can't change my code without
breaking Swagger, and there is no out of the box alternative, API
development just became significantly more difficult. What am I missing?
Thanks,
Jesse Liberty
…On Fri, Sep 27, 2024 at 3:50 PM Safia Abdalla ***@***.***> wrote:
Yes, if you don't make any code changes to your application things should
continue to work as usual.
—
Reply to this email directly, view it on GitHub
<#58103 (reply in thread)>,
or unsubscribe
<https://github.com/notifications/unsubscribe-auth/AAEYGCI365UDZZYJEDGW62DZYWZINAVCNFSM6AAAAABO7ZHZMSVHI2DSMVQWIX3LMV43URDJONRXK43TNFXW4Q3PNVWWK3TUHMYTANZXHE2DOMI>
.
You are receiving this because you commented.Message ID:
***@***.***>
|
Beta Was this translation helpful? Give feedback.
-
|
Since the Swashbuckle project has sprung back to life there is no rush to migrate anytime soon. |
Beta Was this translation helpful? Give feedback.
-
|
I might be missing something here. But it seems microsoft wants us to move from |
Beta Was this translation helpful? Give feedback.
-
|
@martincostello has a share at dotnetconf Copied from martin's blog post
|
Beta Was this translation helpful? Give feedback.
-
|
There are benefits to upgrading (performance, AoT support) but also feature gaps in .NET 9 (XML documentation, an in-box UI). I would imagine the majority of users don't need blazing fast performance or support for native AoT though. If there's nothing specific that catches your eye in the new library, then there's no need to migrate. Both NSwag and Swashbuckle.AspNetCore support .NET 9. |
Beta Was this translation helpful? Give feedback.
-
There's no expectation for you to migrate. This announcement was about removing Swashbuckle.AspNetCore from the built-in web API templates and introducing a built-in solution via the Microsoft.AspNetCore.OpenApi package. Over time, we'll continue to add features to the built-in solution and it'll be the primary delivery vehicle for shipping long-standing enhancements in the OpenAPI space like support for generating security schemes automatically, improvements to build-time code generation, or support for OpenAPI 3.1 (and future versions). If you're successful with Swashbuckle or NSwag (or any other solution) at the moment and you're comfortable with using that dependency in your apps moving forward, then you should totally feel free to do so. |
Beta Was this translation helpful? Give feedback.
-
|
It still might we nice to have some kind of migration guide. We are using all kinds of features from swashbuckle.aspnetcore to make sure our openapi definition is correct like:
There are A LOT of configuration options for swashbuckle.AspNetCore to get openapi documentation correct. Migrating is not as easy as just switching packages and hoping for the best. I'm really surprised there is no documentation at all about migrating We also use npm packages to take our openapi definition to generate typescript code to call the api. This means our openapi definition really has to be correct |
Beta Was this translation helpful? Give feedback.
-
|
I feel like some people are confusing this announcement to mean that "Swashbuckle libraries are being deprecated", which is not the case at all. All that is happening is that Microsoft is not leveraging It's up to each consumer if they want to migrate from their current I don't see how Microsoft needs to provide a "migration guide" either to be honest. As long as the documentation for what it provides is comprehensive, any mentions of mapping between I'm not saying it wouldn't be useful to have such mapping, but people in this thread are acting like its expected or something. You can keep using |
Beta Was this translation helpful? Give feedback.
-
|
It's not exhaustive, but this repo shows how to do the same example things with the new package compared to both NSwag and Swashbuckle as code (not docs) so you can use it to get a rough idea of the differences to compare and contrast: https://github.com/martincostello/aspnetcore-openapi |
Beta Was this translation helpful? Give feedback.
-
|
I'm sorry if I seem to behave as it Microsoft "needs" to create a migration guide. That was not my intention. I would really LIKE to see a migration guide, and I think it will be useful for both many people who WANT (not need) to migrate, and Microsoft who probably want people to start using their new feature. So I think it would make sense to create one |
Beta Was this translation helpful? Give feedback.
-
This is actually wrong assumption which some of us who've been following the ecosystem long enough are aware of. Microsoft typically doesn't care whether any, many or some people use the new feature because the change was introduced to benefit Microsoft themselves. What the reasons might be you can only speculate. Besides, others have already told you that "given how you/your team use OpenAPIs ATM (using mature products like Swashbuckle and/or NSwag) you probably won't be migrating any time soon since there's dozens of features that are missing in MS implementation. What I do hope @martincostello is we will get is a checkbox when creating new projects in Visual Studio to opt-out of the new OpenAPI features, much like Enable Docker checkbox or use Minimal APIs checkbox (I believe there is such a checkbox present when creating new projects). |
Beta Was this translation helpful? Give feedback.
-
|
Ok this is starting to become a toxic discussion. My apologies if I contributed to this, it was not my intention. I simply came here looking for a migration guide, as I think this would help many people who are investigating moving to |
Beta Was this translation helpful? Give feedback.
-
|
This is definitely a documentation question. We need a migration guide :) |
Beta Was this translation helpful? Give feedback.
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.
Beta Was this translation helpful? Give feedback.
All reactions