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.

[l1x]

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

NIH

[RicoSuter]

That's not to say for OpenAPI. NSwag is basically dead, because key issues, such as https://github.com/RicoSuter/NSwag/pull/4888 and https://github.com/RicoSuter/NSwag/pull/4891, aren't being addressed

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...

[darrelmiller]

Kiota (not an official Microsoft product and highly understaffed)

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.

[HavenDV]

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?

[darrelmiller]

@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 It is unrelated to Kiota.

[julealgon]

@darrelmiller it would be indirectly related in the sense that Kiota is supposed to completely supersede AutoREST, correct?

[darrelmiller]

@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.

[julealgon]

@darrelmiller the comment here makes it pretty clear to me that kiota is flat out a superior product. Maybe I misinterpreted it?

• https://github.com/microsoft/kiota/issues/1709#issuecomment-1175085076

... AutoRest works well with APIs that are small, don't have a lot of interconnections/can easily be segmented without loss of functionality ..., and are not too deep (i.e. /path/subpath/subsubpath/subsubsubpath...).

For all those reasons, we've started this generator, which better handles the limitations mentioned above

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.

[kant2002]

@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.

[julealgon]

@kant2002

@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.

[GearTheWorld]

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 ?

[MauriceChocoSwiss]

Hey, what about that https://github.com/domaindrivendev/Swashbuckle.AspNetCore/discussions/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

[diegosasw]

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.

[MauriceChocoSwiss]

@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. Here is the documentation, read the part about Spectral, it show what to add to .csproj file to build the JSON in a directory.

PS: I've made a PR to add option to name the file as we want.

[opcodewriter]

@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.

[Atulin]

After NSwag pissing on my parade with it's lack of support for [FromForm] parameters in Minimal APIs (RicoSuter/NSwag#4626) I'm excited for a first-party implementation. There's at least hope that it will keep up with the changes to the framework.

[mikekistler]

I'm going to move this issue over to discussions now that we have an Announcements category there.