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

[Copilot]

Users migrating from Swashbuckle CLI to .NET 10 lack clear guidance on the built-in replacement. Added a NOTE block highlighting the migration path.

Changes

• Added migration note in "Generate OpenAPI documents at build time" section

  • References Microsoft.AspNetCore.OpenApi for runtime generation
  • References Microsoft.Extensions.ApiDescription.Server for build-time generation (Swashbuckle CLI replacement)
  • Links to UI options documentation (Swagger UI, Scalar)

• Updated metadata: ms.date to current date, added ai-usage: ai-assisted

The note appears immediately before the build-time generation instructions, making it visible to developers searching for Swashbuckle CLI alternatives.

Original prompt

---

This section details on the original issue you should resolve

<issue_title>Generate OpenAPI documents at build time</issue_title>
<issue_description>### Description

Hello,

We are using Swashbuckle CLI to generate swagger at build time with small issues up to now. We want to migrate to .NET 10 but seems that Swashbuckle isn't anymore maintained by it's owner possibly because you removed them from the default option.

Can you please tell us if you have a replacement for the Swashbuckle especially CLI.

Thank you,
Llazar

Page URL

https://learn.microsoft.com/en-us/aspnet/core/fundamentals/openapi/aspnetcore-openapi?view=aspnetcore-10.0&tabs=visual-studio%2Cvisual-studio-code

Content source URL

https://github.com/dotnet/AspNetCore.Docs/blob/main/aspnetcore/fundamentals/openapi/aspnetcore-openapi.md

Document ID

27bad30c-e0b4-10fb-b202-a29d4f8fad24

Platform Id

11e029f8-4c25-d943-fe65-31bfcaf35e2b

Article author

@captainsafia

Metadata

• ID: 27bad30c-e0b4-10fb-b202-a29d4f8fad24
• PlatformId: 11e029f8-4c25-d943-fe65-31bfcaf35e2b
• Service: aspnet-core
• Sub-service: fundamentals

Related Issues</issue_description>

Comments on the Issue (you are @copilot in this section)

@wadepickett Hi @llgjermeni, thank you for reaching out! This is a great question, and you're not alone in looking for guidance on migration related to the Swashbuckle CLI.

ASP.NET Core now has built-in support for generating OpenAPI documents at build time you can use instead. Microsoft.Extensions.ApiDescription.Server package provides this functionality and integrates seamlessly with . NET 10.

Related guidance in the docs:

For build-time document generation (replacement for Swashbuckle CLI), see:

• Generate OpenAPI documents at build time

For interactive API documentation UI (Swagger UI, Scalar, etc.), see:

• [Use Swagger UI for local ad-hoc testing](https://learn.microsoft.com/en-us/aspnet/core/fundamentals/openapi/using-openapi-documents? view=aspnetcore-10.0#use-swagger-ui-for-local-ad-hoc-testing)

---

That said, you raise a valid point. It would be helpful if the documentation more clearly highlighted this as a migration path from Swashbuckle. We'll look into adding a note to make this easier to discover for others in the same situation.

We can use this issue to track addressing that problem.

We could add a note with something along these lines:

> [!NOTE]
> Starting with .NET 9, ASP.NET Core includes built-in OpenAPI support.  The `Microsoft.AspNetCore.OpenApi` package provides OpenAPI document generation at runtime, and adding the `Microsoft.Extensions.ApiDescription.Server` package enables build-time document generation.  For guidance on using interactive UI options like **Swagger UI** or **Scalar**, see [Use the generated OpenAPI documents](xref:fundamentals/openapi/using-openapi-documents).

• Fixes Generate OpenAPI documents at build time #36399

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.

---

Internal previews

📄 File	🔗 Preview link
aspnetcore/fundamentals/openapi/aspnetcore-openapi.md	Generate OpenAPI documents