diff --git a/docs/en/Community-Articles/2024-11-13-BuiltIn-OpenApi-Documentation/cover.png b/docs/en/Community-Articles/2024-11-13-BuiltIn-OpenApi-Documentation/cover.png index b7dbfab3a8..4ac79513c3 100644 Binary files a/docs/en/Community-Articles/2024-11-13-BuiltIn-OpenApi-Documentation/cover.png and b/docs/en/Community-Articles/2024-11-13-BuiltIn-OpenApi-Documentation/cover.png differ diff --git a/docs/en/Community-Articles/2024-11-13-BuiltIn-OpenApi-Documentation/img2.png b/docs/en/Community-Articles/2024-11-13-BuiltIn-OpenApi-Documentation/img2.png index 179250369e..87076b1329 100644 Binary files a/docs/en/Community-Articles/2024-11-13-BuiltIn-OpenApi-Documentation/img2.png and b/docs/en/Community-Articles/2024-11-13-BuiltIn-OpenApi-Documentation/img2.png differ diff --git a/docs/en/Community-Articles/2024-11-13-BuiltIn-OpenApi-Documentation/post.md b/docs/en/Community-Articles/2024-11-13-BuiltIn-OpenApi-Documentation/post.md index e729f12aff..df14f0e8c5 100644 --- a/docs/en/Community-Articles/2024-11-13-BuiltIn-OpenApi-Documentation/post.md +++ b/docs/en/Community-Articles/2024-11-13-BuiltIn-OpenApi-Documentation/post.md @@ -6,92 +6,121 @@ Built-in OpenAPI Document Generation with .NET 9 β€” No more SwaggerUI! πŸ‘‹ What’s Swagger UI? ------------------ -[Swagger UI](https://swagger.io/) is an open-source tool that automatically generates an interactive, web-based documentation interface for APIs defined using the OpenAPI Specification (OAS). It simplifies the process of exploring and testing APIs directly from the browser, making it a popular choice for developers and API consumers. It provides paid also free services. +[Swagger UI](https://swagger.io/) is an open-source tool that automatically generates an interactive, web-based documentation interface for WebAPIs. +It supports OpenAPI standards. It was very popular tool among the ASP.NET Core developers from 2020 to 2024. +Because it was a built-in tool comes with ASP.NET Core default templates. +We liked this tool because it was the first tool that allows us to make WebAPI calls for testing. +Now it provides paid services as well as free ones. + +> Previously, Swagger was included by default from **.NET 5** to **.NET 8** in .NET web templates. + +--- + -> Previously, Swagger was included by default from **.NET 5** to **.NET 8**, which provides OpenAPI support. What’s OpenAPI? --------------- -OpenAPI is a standard specification for defining RESTful APIs. Its website is [https://www.openapis.org/](https://www.openapis.org/). Their specifications let developers create, understand, document, and integrate APIs more efficiently. +OpenAPI is a standard specification for defining REST APIs. +The official website is [https://www.openapis.org/](https://www.openapis.org/). +Microsoft is now using OpenAPI and here is the official documentation πŸ‘‰ [https://aka.ms/aspnet/openapi](https://aka.ms/aspnet/openapi) + +--- -OpenAPI Microsoft Documentation πŸ‘‰ [https://aka.ms/aspnet/openapi](https://aka.ms/aspnet/openapi) -Replacement of Swagger UI with OpenAPI for API projects β€” Bye Swashbuckle πŸ‘‹ + +Replacement of Swagger UI with OpenAPI ---------------------------------------------------------------------------- +Swagger UI is no longer integrated into NET 9, as Microsoft wants a solution with first-class support, better control, and enhanced security. As you see in the below screenshot, Microsoft declares that it's already removed. + ![Docs](img2.png) -Swagger UI, a third-party tool used for documenting and testing APIs, is no longer integrated into NET 9, as Microsoft wants a solution with first-class support, better control, and enhanced security. +--- + + + + + +## Why is Swagger Removed from .NET 9? + +In March 2024, the ASP.NET Core team announced that they are removing the `Swashbuckle.AspNetCore` dependency from web templates from .NET 9 release. + -In March 2024, the ASP.NET Core team announced plans to remove the `Swashbuckle.AspNetCore` dependency from web API templates in the upcoming .NET 9 release. > This decision was influenced by the project's lack of active maintenance and the absence of an official release for .NET 8. -The team intends to enhance the `Microsoft.AspNetCore.OpenApi` package to provide built-in OpenAPI document generation capabilities, reducing reliance on external tools. Community members expressed concerns about the inactivity of Swashbuckle and discussed alternatives like contributing to or forking the project. The ASP.NET Core team has engaged with the maintainers of both Swashbuckle and NSwag to explore potential collaborations and ensure a smooth transition for developers. -In the below issue, you can see the details of this decision: -* https://github.com/dotnet/aspnetcore/issues/54599 +Microsoft team created a new package `Microsoft.AspNetCore.OpenApi`. It provides built-in OpenAPI document generation just like Swagger. So Microsoft doesn't depend on external tools. Because in every .NET release, they need to ask the owners of the external tool libraries to align with their new version. And sometimes these library owners cannot update their code-base according to the recent .NET changes. And it is becoming harder for Microsoft to support the 3rd party libraries under these circumstances. Basically reducing 3rd party dependencies will help Microsoft fast release cycles. +I read Reddit, GitHub discussions and YouTube reviews about this topic. As I see community members expressed concerns about the inactivity of Swashbuckle and they are discussing alternatives like contributing to or forking the project. The Microsoft team also contacted the owners of Swashbuckle and NSwag to explore potential collaborations and ensure a smooth transition for developers. +In the below GitHub issue, you can see the details of this decision: -**Jeremy** -Product Manager- at Microsoft answers why they took this decision in [this post](https://github.com/dotnet/aspnetcore/issues/54599#issuecomment-2004975574). +* [github.com/dotnet/aspnetcore/issues/54599](https://github.com/dotnet/aspnetcore/issues/54599) + + + +**Jeremy** -Product Manager- at Microsoft, answers why they took this decision in [this post](https://github.com/dotnet/aspnetcore/issues/54599#issuecomment-2004975574). ![Jeremy Comments](img3.png) -Why is SwaggerUI Removed from .NET 9? -------------------------------------- +As a summary; + +**The change is due to a lack of maintenance of the Swagger library**, although it has seen some recent updates. This aims to reduce dependency on external tools and provide a streamlined, out-of-the-box experience for generating OpenAPI documentation for ASP.NET Core Web APIs. -**The change is due to a lack of maintenance of the Swagger library**, although it has seen some recent updates. +--- -This change aims to reduce dependency on external tools and provide a streamlined, out-of-the-box experience for generating OpenAPI documentation for ASP.NET Core Web APIs. -What are the Benefits of the New OpenAI Documentation? + +What are the Benefits of the New OpenAI Package? --------------------------------------------------------------- -1. **Native Support and Reduced Dependency** +### Native Support and Reduced Dependency + +The new `Microsoft.AspNetCore.OpenApi` package provides first-class citizen support for OpenAPI. It reduces reliance on external tools like Swashbuckle or NSwag for basic documentation needs. The native implementation leverages source generators to reduce runtime overhead. -The new `Microsoft.AspNetCore.OpenApi` package provides first-class support for OpenAPI.Reduces reliance on external tools like Swashbuckle or NSwag for basic documentation needs. +### Simplified Configuration -2. **Simplified Configuration** +No need extra setup or 3rd party integrations. Just by defining controllers and endpoints, ASP.NET Core automatically generates OpenAPI specifications. -No need for extensive setup or third-party integrations. Just by defining controllers and endpoints, the framework can automatically generate OpenAPI specifications. +### Wel Integration with Minimal APIs -3. **Better Integration with Minimal APIs** +[Minimal APIs](https://learn.microsoft.com/en-us/aspnet/core/fundamentals/minimal-apis) introduced in .NET 6. There's an optimized built-in support for Minimal APIs. It automatically adds metadata for routes, request parameters, and responses. -- The built-in support is optimized for **Minimal APIs**, a feature introduced in .NET 6. Automatically includes metadata for routes, request parameters, and responses. +### Compatibility with Existing Tools -4. **Performance Improvement** +You can still use the output of OpenAPI with Swagger or NSwag... So it doesn't mean that in this case you have only one option when you use OpenAPI. -- The native implementation leverages source generators to reduce runtime overhead. Faster and more efficient than traditional runtime-based solutions like Swashbuckle. +--- -5. **Compatibility with Existing Tools** -* The OpenAPI output can still be consumed by Swagger UI, NSwag, or other tools for visualization, testing, or client generation. How to Use the New OpenAPI in .NET9? ------------------------------------ -If you are creating a new ASP.NET Core project, you can see the below checkbox to add OpenAPI. +When you create a new ASP.NET Core project, you can see the below checkbox to add OpenAPI. ![New .NET 9 Project Screen](img5.png) -When I created a new .NET 9 web project, I saw that OpenAPI had already been added. +I created a new .NET 9 web project, I saw that OpenAPI had already been added. ![Package Reference](img4.png) -Add the required NuGet package [Microsoft.AspNetCore.OpenApi](https://www.nuget.org/packages/Microsoft.AspNetCore.OpenApi) +## Add OpenAPI Support For Your Existing Project + +Upgrade your project to .NET 9 and add the required NuGet package [Microsoft.AspNetCore.OpenApi](https://www.nuget.org/packages/Microsoft.AspNetCore.OpenApi) ``` dotnet add package Microsoft.AspNetCore.OpenApi ``` -### Enable OpenAPI Support +### Add the following services and middleware in `Program.cs` @@ -110,6 +139,10 @@ Change the port to your active port. This is how it looks like: ![Web UI of the Documentation](img1.png) +--- + + + Alternative 3rd Party Tool: Scalar ================================== @@ -119,6 +152,11 @@ See the repo πŸ‘‰ [https://github.com/scalar/scalar](https://github.com/scalar/s +That's all from the replacement of Swagger in .NET 9. +Happy coding πŸ‘¨β€πŸ’» + + + **References** * [https://learn.microsoft.com/en-us/aspnet/core/release-notes/aspnetcore-9.0?view=aspnetcore-8.0#openapi](https://learn.microsoft.com/en-us/aspnet/core/release-notes/aspnetcore-9.0?view=aspnetcore-8.0#openapi)