Announcement: Swashbuckle.AspNetCore is being removed in .NET 9 #58103
Replies: 71 comments 9 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.
-
|
@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. |
Beta Was this translation helpful? Give feedback.
-
|
@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. |
Beta Was this translation helpful? Give feedback.
-
|
@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. |
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.
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