Add SchemaRepository.ReplaceSchemaId() (#3708)

* Add public method SchemaRepository.ReplaceSchemaId

* Review feedback

* More review feedback

Author: bkoelman

Directory.Build.props

@@ -37,7 +37,7 @@
     <SymbolPackageFormat>snupkg</SymbolPackageFormat>
     <TreatWarningsAsErrors>true</TreatWarningsAsErrors>
     <UseArtifactsOutput>true</UseArtifactsOutput>
-    <VersionPrefix>10.0.2</VersionPrefix>
+    <VersionPrefix>10.1.0</VersionPrefix>
     <WarnOnPackingNonPackableProject>false</WarnOnPackingNonPackableProject>
   </PropertyGroup>
   <PropertyGroup Condition=" '$(GITHUB_ACTIONS)' != '' AND '$(DEPENDABOT_JOB_ID)' == '' ">

src/Swashbuckle.AspNetCore.SwaggerGen/PublicAPI/PublicAPI.Unshipped.txt

@@ -1 +1 @@
-
+Swashbuckle.AspNetCore.SwaggerGen.SchemaRepository.ReplaceSchemaId(System.Type schemaType, string replacementSchemaId) -> bool

src/Swashbuckle.AspNetCore.SwaggerGen/SwaggerGenerator/SchemaRepository.cs

@@ -42,4 +42,24 @@ public OpenApiSchemaReference AddDefinition(string schemaId, OpenApiSchema schem
 
         return new OpenApiSchemaReference(schemaId);
     }
+
+    public bool ReplaceSchemaId(Type schemaType, string replacementSchemaId)
+    {
+        ArgumentNullException.ThrowIfNull(schemaType);
+        ArgumentException.ThrowIfNullOrEmpty(replacementSchemaId);
+
+        if (_reservedIds.TryGetValue(schemaType, out string oldSchemaId) &&
+            oldSchemaId != replacementSchemaId &&
+            Schemas.TryGetValue(oldSchemaId, out var targetSchema))
+        {
+            if (Schemas.TryAdd(replacementSchemaId, targetSchema))
+            {
+                Schemas.Remove(oldSchemaId);
+                _reservedIds.Remove(schemaType);
+                return true;
+            }
+        }
+
+        return false;
+    }
 }

test/Swashbuckle.AspNetCore.SwaggerGen.Test/SchemaRepositoryTests.cs

@@ -0,0 +1,119 @@
+using Microsoft.OpenApi;
+
+namespace Swashbuckle.AspNetCore.SwaggerGen.Test;
+
+public static class SchemaRepositoryTests
+{
+    [Fact]
+    public static void ReplaceSchemaId_ExistingSchema_ReplacesSchemaId()
+    {
+        var repository = new SchemaRepository();
+        (string oldSchemaId, IOpenApiSchema exampleSchema) = GenerateSchemaForType(typeof(Example), repository);
+
+        string newSchemaId = "alternateId";
+        bool result = repository.ReplaceSchemaId(typeof(Example), newSchemaId);
+
+        Assert.True(result);
+        Assert.DoesNotContain(oldSchemaId, repository.Schemas);
+        Assert.Contains(newSchemaId, repository.Schemas);
+        Assert.Same(exampleSchema, repository.Schemas[newSchemaId]);
+    }
+
+    [Fact]
+    public static void ReplaceSchemaId_MultipleSchemas_ReplacesSchemaId()
+    {
+        var repository = new SchemaRepository();
+        (string oldSchemaId, IOpenApiSchema exampleSchema) = GenerateSchemaForType(typeof(Example), repository);
+        (string otherSchemaId, IOpenApiSchema otherSchema) = GenerateSchemaForType(typeof(Exception), repository);
+
+        string newSchemaId = "alternateId";
+        bool result = repository.ReplaceSchemaId(typeof(Example), newSchemaId);
+
+        Assert.True(result);
+        Assert.DoesNotContain(oldSchemaId, repository.Schemas);
+        Assert.Contains(newSchemaId, repository.Schemas);
+        Assert.Same(exampleSchema, repository.Schemas[newSchemaId]);
+        Assert.Contains(otherSchemaId, repository.Schemas);
+        Assert.Same(otherSchema, repository.Schemas[otherSchemaId]);
+    }
+
+    [Fact]
+    public static void ReplaceSchemaId_MissingSchema_DoesNotChange()
+    {
+        var repository = new SchemaRepository();
+
+        string newSchemaId = "alternateId";
+        bool result = repository.ReplaceSchemaId(typeof(Example), newSchemaId);
+
+        Assert.False(result);
+        Assert.DoesNotContain(newSchemaId, repository.Schemas);
+    }
+
+    [Fact]
+    public static void ReplaceSchemaId_UnchangedId_DoesNotChange()
+    {
+        var repository = new SchemaRepository();
+        (string schemaId, IOpenApiSchema exampleSchema) = GenerateSchemaForType(typeof(Example), repository);
+
+        bool result = repository.ReplaceSchemaId(typeof(Example), schemaId);
+
+        Assert.False(result);
+        Assert.Contains(schemaId, repository.Schemas);
+        Assert.Same(exampleSchema, repository.Schemas[schemaId]);
+    }
+
+    [Fact]
+    public static void ReplaceSchemaId_ExistingId_DoesNotChange()
+    {
+        var repository = new SchemaRepository();
+
+        var otherSchema = new OpenApiSchema();
+        string otherSchemaId = "alreadyInUse";
+        repository.Schemas.Add(otherSchemaId, otherSchema);
+
+        GenerateSchemaForType(typeof(Example), repository);
+
+        bool result = repository.ReplaceSchemaId(typeof(Example), otherSchemaId);
+
+        Assert.False(result);
+        Assert.Contains(otherSchemaId, repository.Schemas);
+        Assert.Same(otherSchema, repository.Schemas[otherSchemaId]);
+    }
+
+    [Fact]
+    public static void ReplaceSchemaId_CanGenerateMultipleTimes()
+    {
+        var repository = new SchemaRepository();
+        GenerateSchemaForType(typeof(Example), repository);
+
+        string newSchemaId1 = "exampleVariant1";
+        bool result1 = repository.ReplaceSchemaId(typeof(Example), newSchemaId1);
+        Assert.True(result1);
+
+        GenerateSchemaForType(typeof(Example), repository);
+
+        string newSchemaId2 = "exampleVariant2";
+        bool result2 = repository.ReplaceSchemaId(typeof(Example), newSchemaId2);
+        Assert.True(result2);
+
+        Assert.Equal(2, repository.Schemas.Count);
+        Assert.Contains(newSchemaId1, repository.Schemas);
+        Assert.Contains(newSchemaId2, repository.Schemas);
+    }
+
+    private static (string, IOpenApiSchema) GenerateSchemaForType(Type type, SchemaRepository repository)
+    {
+        var generator = new SchemaGenerator(new(), new JsonSerializerDataContractResolver(new()));
+        var schemaReference = (OpenApiSchemaReference)generator.GenerateSchema(type, repository);
+
+        string schemaId = schemaReference.Reference.Id!;
+        IOpenApiSchema schema = repository.Schemas[schemaId];
+
+        return (schemaId, schema);
+    }
+
+    private sealed class Example
+    {
+        public string Value { get; set; }
+    }
+}