Upgrade Swashbuckle.AspNetCore to v10

docs/modules/ROOT/pages/changelog.adoc

@@ -20,6 +20,11 @@ the link to the GitHub tag is only added once we are ready to release.
 :github-issue: https://github.com/peopleware/net-ppwcode-aspnetcore-host/issues/
 
 
+:release: 2.0.0
+== `{release}`
+include::partial$changelog-release-section.adoc[]
+include::partial$changelog-{release}.adoc[]
+
 :release: 1.0.0
 == `{release}`
 include::partial$changelog-release-section.adoc[]

docs/modules/ROOT/partials/changelog-2.0.0.adoc

@@ -0,0 +1,18 @@
+////
+The changelog for a specific release.
+Note that it is best to update the changelog as new code is developed.
+
+All attributes used, must be included in this file to keep it self-contained.
+
+This file is translated into markdown and used for the release notes in the GitHub release!
+////
+
+=== Changes
+* Switch to .NET SDK `10.0.201`
+* Upgrade `Swashbuckle.AspNetCore` from `7.3.2` to `10.1.7`
+** Fixes link:{github-issue}1[#1] in link:{github-pr}2[#2] by link:{github-user}rvdginste[@rvdginste]
+
+
+=== Note: breaking change
+* Rename `INSSSchemaFilter` to `ForceTypeToStringSchemaFilter`
+* Changes to the provided `IOperationFilter` implementations after upgrade to new major version of `Swashbuckle.AspNetCore`

global.json

@@ -1,6 +1,6 @@
 {
   "sdk": {
     "rollForward": "disable",
-    "version": "10.0.102"
+    "version": "10.0.201"
   }
 }

src/Directory.Packages.props

@@ -50,8 +50,8 @@
         <PackageVersion Include="PPWCode.AspNetCore.Server.I" Version="1.*" />
 
         <!-- Swashbuckle -->
-        <PackageVersion Include="Swashbuckle.AspNetCore" Version="7.*"/>
-        <PackageVersion Include="Swashbuckle.AspNetCore.Annotations" Version="7.*" />
+        <PackageVersion Include="Swashbuckle.AspNetCore" Version="10.*"/>
+        <PackageVersion Include="Swashbuckle.AspNetCore.Annotations" Version="10.*" />
 
         <!-- Asp.Versioning -->
         <PackageVersion Include="Asp.Versioning.Mvc.ApiExplorer" Version="8.*" />

src/I/Swagger/AddDefaultRequiredFields.cs

@@ -1,4 +1,4 @@
-// Copyright 2025 by PeopleWare n.v..
+// Copyright 2026 by PeopleWare n.v..
 // Licensed under the Apache License, Version 2.0 (the "License");
 // you may not use this file except in compliance with the License.
 // You may obtain a copy of the License at
@@ -11,14 +11,16 @@
 
 using System.Collections.ObjectModel;
 using System.Diagnostics.CodeAnalysis;
+using System.Text.Json.Nodes;
 
 using Asp.Versioning;
 
 using Microsoft.AspNetCore.Mvc.ApiExplorer;
-using Microsoft.OpenApi.Any;
-using Microsoft.OpenApi.Models;
+using Microsoft.OpenApi;
 
 using PPWCode.AspNetCore.Host.I.Bootstrap;
+using PPWCode.Vernacular.Contracts.I;
+using PPWCode.Vernacular.Exceptions.V;
 
 using Swashbuckle.AspNetCore.SwaggerGen;
 
@@ -36,7 +38,7 @@ static AddDefaultRequiredFields()
                 new(
                     typeof(ApiVersion),
                     [
-                        (pd => $"{pd.ParameterDescriptor.Name}", new OpenApiString($"{Startup.DefaultApiVersion.ToString(Startup.ApiVersionFormat)}"))
+                        (pd => $"{pd.ParameterDescriptor.Name}", JsonValue.Create($"{Startup.DefaultApiVersion.ToString(Startup.ApiVersionFormat)}"))
                     ]);
             _requiredFieldsWithDefaultValues.Add(defaultRequiredField);
         }
@@ -63,36 +65,49 @@ public override void Apply(OpenApiOperation operation, OperationFilterContext co
                     continue;
                 }
 
-                foreach ((Func<ApiParameterDescription, string>, IOpenApiAny) tuple in defaultRequiredField.ParamLambdas)
+                foreach ((Func<ApiParameterDescription, string>, JsonNode) tuple in defaultRequiredField.ParamLambdas)
                 {
                     SetParamValue(operation, tuple.Item1.Invoke(parameter), tuple.Item2);
                 }
             }
         }
 
-        protected void SetParamValue(OpenApiOperation operation, string name, IOpenApiAny defaultValue)
+        protected void SetParamValue(OpenApiOperation operation, string name, JsonNode defaultValue)
         {
-            OpenApiParameter? param =
+            Contract.Requires(operation.Parameters is not null);
+            IOpenApiParameter? parameter =
                 operation
                     .Parameters
                     .SingleOrDefault(p => string.Equals(p.Name, name, StringComparison.OrdinalIgnoreCase));
-            if (param is { Required: true })
+
+            if (parameter is not null)
             {
-                param.Example = defaultValue;
+                OpenApiParameter? openApiParameter =
+                    parameter switch
+                    {
+                        OpenApiParameter openApiParameterTemp => openApiParameterTemp,
+                        OpenApiParameterReference openApiParameterReference => openApiParameterReference.RecursiveTarget,
+                        _ => throw new ProgrammingError("Unsupported configuration")
+                    };
+
+                if (openApiParameter is not null && openApiParameter.Required)
+                {
+                    openApiParameter.Example = defaultValue;
+                }
             }
         }
 
         public class DefaultRequiredField
         {
-            public DefaultRequiredField(Type type, (Func<ApiParameterDescription, string>, IOpenApiAny)[] paramLambdas)
+            public DefaultRequiredField(Type type, (Func<ApiParameterDescription, string>, JsonNode)[] paramLambdas)
             {
                 Type = type;
                 ParamLambdas = paramLambdas;
             }
 
             public Type Type { get; }
 
-            public (Func<ApiParameterDescription, string>, IOpenApiAny)[] ParamLambdas { get; }
+            public (Func<ApiParameterDescription, string>, JsonNode)[] ParamLambdas { get; }
         }
     }
 }

src/I/Swagger/AddNoContentCodes.cs

@@ -1,4 +1,4 @@
-// Copyright 2025 by PeopleWare n.v..
+// Copyright 2026 by PeopleWare n.v..
 // Licensed under the Apache License, Version 2.0 (the "License");
 // you may not use this file except in compliance with the License.
 // You may obtain a copy of the License at
@@ -12,7 +12,7 @@
 using System.Diagnostics.CodeAnalysis;
 using System.Net;
 
-using Microsoft.OpenApi.Models;
+using Microsoft.OpenApi;
 
 using Swashbuckle.AspNetCore.SwaggerGen;
 

src/I/Swagger/AddNotFoundResponseCodes.cs

@@ -1,4 +1,4 @@
-// Copyright 2025 by PeopleWare n.v..
+// Copyright 2026 by PeopleWare n.v..
 // Licensed under the Apache License, Version 2.0 (the "License");
 // you may not use this file except in compliance with the License.
 // You may obtain a copy of the License at
@@ -16,7 +16,7 @@
 
 using Microsoft.AspNetCore.Mvc.ApiExplorer;
 using Microsoft.AspNetCore.Mvc.ModelBinding;
-using Microsoft.OpenApi.Models;
+using Microsoft.OpenApi;
 
 using Swashbuckle.AspNetCore.SwaggerGen;
 

src/I/Swagger/AddRequestSimulationHeader.cs

@@ -1,4 +1,4 @@
-// Copyright 2025 by PeopleWare n.v..
+// Copyright 2026 by PeopleWare n.v..
 // Licensed under the Apache License, Version 2.0 (the "License");
 // you may not use this file except in compliance with the License.
 // You may obtain a copy of the License at
@@ -11,7 +11,7 @@
 
 using System.Diagnostics.CodeAnalysis;
 
-using Microsoft.OpenApi.Models;
+using Microsoft.OpenApi;
 
 using PPWCode.AspNetCore.Host.I.Transactional;
 
@@ -32,7 +32,7 @@ public override void Apply(OpenApiOperation operation, OperationFilterContext co
         {
             if (IsPost(context) || IsPut(context) || IsDelete(context))
             {
-                operation.Parameters ??= new List<OpenApiParameter>();
+                operation.Parameters ??= new List<IOpenApiParameter>();
                 operation.Parameters.Add(
                     new OpenApiParameter
                     {
@@ -42,7 +42,7 @@ public override void Apply(OpenApiOperation operation, OperationFilterContext co
                         Schema =
                             new OpenApiSchema
                             {
-                                Type = "string"
+                                Type = JsonSchemaType.String
                             },
                         Required = false,
                     });

src/I/Swagger/AddSemanticFaultResponseCodes.cs

@@ -1,4 +1,4 @@
-// Copyright 2025 by PeopleWare n.v..
+// Copyright 2026 by PeopleWare n.v..
 // Licensed under the Apache License, Version 2.0 (the "License");
 // you may not use this file except in compliance with the License.
 // You may obtain a copy of the License at
@@ -12,7 +12,7 @@
 using System.Diagnostics.CodeAnalysis;
 using System.Net;
 
-using Microsoft.OpenApi.Models;
+using Microsoft.OpenApi;
 
 using Swashbuckle.AspNetCore.SwaggerGen;
 
@@ -25,7 +25,7 @@ public class AddSemanticFaultResponseCodes : PpwOperationFilter
         /// <inheritdoc />
         public override void Apply(OpenApiOperation operation, OperationFilterContext context)
         {
-            OpenApiResponse response = new OpenApiResponse { Description = "Parameter validation failed or some business rules were not fulfilled." };
+            OpenApiResponse response = new() { Description = "Parameter validation failed or some business rules were not fulfilled." };
             ConditionalAddResponse(operation, $"{HttpStatusCode.BadRequest:D}", response);
         }
     }

src/I/Swagger/AddTransactionalInformation.cs

@@ -1,4 +1,4 @@
-// Copyright 2025 by PeopleWare n.v..
+// Copyright 2026 by PeopleWare n.v..
 // Licensed under the Apache License, Version 2.0 (the "License");
 // you may not use this file except in compliance with the License.
 // You may obtain a copy of the License at
@@ -14,7 +14,7 @@
 using System.Text;
 
 using Microsoft.AspNetCore.Mvc.Controllers;
-using Microsoft.OpenApi.Models;
+using Microsoft.OpenApi;
 
 using PPWCode.AspNetCore.Server.I.Transactional;
 

src/I/Swagger/ForceTypeToStringSchemaFilter.cs

@@ -0,0 +1,34 @@
+using Microsoft.OpenApi;
+
+using PPWCode.Vernacular.Contracts.I;
+using PPWCode.Vernacular.Exceptions.V;
+
+using Swashbuckle.AspNetCore.SwaggerGen;
+
+namespace PPWCode.AspNetCore.Host.I.Swagger;
+
+public class ForceTypeToStringSchemaFilter<T> : ISchemaFilter
+    where T : class
+{
+    /// <inheritdoc />
+    public void Apply(IOpenApiSchema schema, SchemaFilterContext context)
+    {
+        OpenApiSchema? openApiSchema =
+            schema switch
+            {
+                OpenApiSchema openApiSchemaTemp => openApiSchemaTemp,
+                OpenApiSchemaReference openApiSchemaReference => openApiSchemaReference.RecursiveTarget,
+                _ => throw new ProgrammingError("Unsupported configuration")
+            };
+
+        if (openApiSchema is not null && (context.Type == typeof(T)))
+        {
+            // Override schema to be a string
+            openApiSchema.Type = JsonSchemaType.String;
+
+            // Remove properties (e.g., "value")
+            Contract.Assert(openApiSchema.Properties != null);
+            openApiSchema.Properties.Clear();
+        }
+    }
+}

src/I/Swagger/PpwOperationFilter.cs

@@ -1,4 +1,4 @@
-// Copyright 2025 by PeopleWare n.v..
+// Copyright 2026 by PeopleWare n.v..
 // Licensed under the Apache License, Version 2.0 (the "License");
 // you may not use this file except in compliance with the License.
 // You may obtain a copy of the License at
@@ -13,8 +13,9 @@
 
 using Microsoft.AspNetCore.Mvc.ApiExplorer;
 using Microsoft.AspNetCore.Mvc.Controllers;
-using Microsoft.OpenApi.Models;
+using Microsoft.OpenApi;
 
+using PPWCode.Vernacular.Contracts.I;
 using PPWCode.Vernacular.Persistence.V;
 
 using Swashbuckle.AspNetCore.SwaggerGen;
@@ -69,15 +70,20 @@ protected virtual string GetIdentifications(ApiDescription apiDescription, Func<
                     .Select(GetIdentification));
 
         protected virtual bool ResponseExists(OpenApiOperation operation, string key)
-            => operation.Responses.ContainsKey(key);
+        {
+            Contract.Requires(operation.Responses is not null);
+            return operation.Responses.ContainsKey(key);
+        }
 
         protected virtual void AddResponse(OpenApiOperation operation, string key, OpenApiResponse response)
         {
+            Contract.Requires(operation.Responses is not null);
             operation.Responses.Add(key, response);
         }
 
         protected virtual void RemoveResponse(OpenApiOperation operation, string key)
         {
+            Contract.Requires(operation.Responses is not null);
             if (ResponseExists(operation, key))
             {
                 operation.Responses.Remove(key);