From ee9f0b7bf0b38b4e67b2d1f589523c4e2f4e7f52 Mon Sep 17 00:00:00 2001
From: Andy Butland <abutland73@gmail.com>
Date: Mon, 23 Feb 2026 12:49:25 +0100
Subject: [PATCH] Ensure Swashbuckle version is aligned with Umbraco in the
 extension template.

---
 Directory.Packages.props                            |  3 ++-
 templates/UmbracoExtension/Umbraco.Extension.csproj | 13 +++++++++++++
 2 files changed, 15 insertions(+), 1 deletion(-)

diff --git a/Directory.Packages.props b/Directory.Packages.props
index 8a32d0745480..3ee01cb52f6a 100644
--- a/Directory.Packages.props
+++ b/Directory.Packages.props
@@ -76,7 +76,8 @@
     <PackageVersion Include="Serilog.Sinks.Map" Version="2.0.0" />
     <PackageVersion Include="SixLabors.ImageSharp" Version="3.1.12" />
     <PackageVersion Include="SixLabors.ImageSharp.Web" Version="3.2.0" />
-    <PackageVersion Include="Swashbuckle.AspNetCore" Version="10.1.0" />
+    <!-- When updating this version, also update templates/UmbracoExtension/Umbraco.Extension.csproj -->
+    <PackageVersion Include="Swashbuckle.AspNetCore" Version="10.1.4" />
   </ItemGroup>
   <!-- Transitive pinned versions (only required because our direct dependencies have vulnerable versions of transitive dependencies) -->
   <ItemGroup>
diff --git a/templates/UmbracoExtension/Umbraco.Extension.csproj b/templates/UmbracoExtension/Umbraco.Extension.csproj
index 1e515aebbf82..0e92a0c92ffe 100644
--- a/templates/UmbracoExtension/Umbraco.Extension.csproj
+++ b/templates/UmbracoExtension/Umbraco.Extension.csproj
@@ -23,6 +23,19 @@
     <PackageReference Include="Umbraco.Cms.Web.Common" Version="UMBRACO_VERSION_FROM_TEMPLATE" />
     <PackageReference Include="Umbraco.Cms.Api.Common" Version="UMBRACO_VERSION_FROM_TEMPLATE" />
     <PackageReference Include="Umbraco.Cms.Api.Management" Version="UMBRACO_VERSION_FROM_TEMPLATE" />
+
+    <!--
+      Swashbuckle is available transitively from the Umbraco packages above, but we take a direct
+      dependency here because extension code directly uses types from Swashbuckle (SwaggerGenOptions)
+      and Microsoft.OpenApi (OpenApiInfo). Without a direct reference, this project's Swashbuckle
+      version is determined solely by NuGet's transitive resolution, which can resolve to a different
+      version than the host site project (e.g. a newer patch). When that happens, the different
+      Microsoft.OpenApi versions (a transitive dependency of Swashbuckle) can conflict at runtime,
+      causing custom Swagger documents registered by the extension to fail to appear.
+      Most other transitive dependencies don't have this problem because extension code doesn't
+      use their types directly - only Swashbuckle/OpenApi types are referenced in the composer.
+    -->
+    <PackageReference Include="Swashbuckle.AspNetCore" Version="10.1.4" />
   </ItemGroup>
 
   <ItemGroup>