Skip to content

Add migration note for Swashbuckle CLI to built-in OpenAPI support #36512

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
wadepickett merged 8 commits into from
Jan 6, 2026
Merged

Add migration note for Swashbuckle CLI to built-in OpenAPI support #36512

Changes from all commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
f90df8f
Initial plan
Copilot Dec 17, 2025
1839b11
Add migration note for Swashbuckle CLI users to built-in OpenAPI support
Copilot Dec 17, 2025
c035e34
Apply suggestion from @wadepickett
wadepickett Dec 18, 2025
d359bf2
Apply suggestion from @wadepickett
wadepickett Jan 5, 2026
9532ef8
Apply suggestion from @wadepickett
wadepickett Jan 5, 2026
f5c4a6d
Apply suggestion from @wadepickett
wadepickett Jan 5, 2026
7c1a918
Apply suggestion from @wadepickett
wadepickett Jan 5, 2026
4a581f4
Apply suggestion from @wadepickett
wadepickett Jan 5, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 8 additions & 2 deletions aspnetcore/fundamentals/openapi/aspnetcore-openapi.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,11 +1,12 @@
---
title: Generate OpenAPI documents
ai-usage: ai-assisted
author: captainsafia
description: Learn how to generate and customize OpenAPI documents in an ASP.NET Core app.
ms.author: safia
monikerRange: '>= aspnetcore-6.0'
ms.author: safia
ms.custom: mvc
ms.date: 12/10/2025
ms.date: 12/17/2025
uid: fundamentals/openapi/aspnetcore-openapi
---
# Generate OpenAPI documents
Expand Down Expand Up @@ -183,6 +184,11 @@ You can customize the <xref:Microsoft.AspNetCore.OpenApi.OpenApiOptions.ShouldIn

## Generate OpenAPI documents at build time

> [!NOTE]
> Starting with .NET 9, ASP.NET Core includes built-in OpenAPI support. The [`Microsoft.AspNetCore.OpenApi`](https://www.nuget.org/packages/Microsoft.AspNetCore.OpenApi) package provides OpenAPI document generation at runtime, and adding the [`Microsoft.Extensions.ApiDescription.Server` ](https://www.nuget.org/packages/Microsoft.Extensions.ApiDescription.Server) package enables build-time document generation.
>
>ASP.NET Core generates OpenAPI documents only. Interactive UIs such as **Swagger UI** or **Scalar** are not included by default and must be added separately. For guidance on using these UI options, see <xref:fundamentals/openapi/using-openapi-documents>.

In typical web apps, OpenAPI documents are generated at runtime and served via an HTTP request to the app server.

In some scenarios, it's helpful to generate the OpenAPI document during the app's build step. These scenarios include generating OpenAPI documentation that is:
Expand Down