Add UseFullTypeNameSchemaIds extension for OpenAPI schema reference IDs (#291)

Author: marcominerva

samples/TinyHelpers.AspNetCore.Sample/Program.cs

@@ -68,6 +68,10 @@
 
     // Add time examples for TimeSpan and TimeOnly fields.
     options.AddTimeExamples();
+
+    // Uncomment to use full type names (including namespace) for schema IDs.
+    // This helps avoid naming collisions when multiple types have the same name.
+    // options.UseFullTypeNameSchemaIds();
 });
 
 // Add default problem details and exception handler.

src/TinyHelpers.AspNetCore/OpenApi/OpenApiExtensions.cs

@@ -54,6 +54,32 @@ public static OpenApiOptions EnableEnumSupport(this OpenApiOptions options)
         => options.AddSchemaTransformer<EnumSchemaTransformer>();
 #endif
 
+    /// <summary>
+    /// Configures the OpenAPI schema reference IDs to use the full type name (including namespace) 
+    /// instead of just the type name. This helps avoid naming collisions when multiple types have the same name.
+    /// </summary>
+    /// <param name="options">The <see cref="OpenApiOptions"/> to configure.</param>
+    /// <returns>The <see cref="OpenApiOptions"/> instance for further customization.</returns>
+    /// <remarks>
+    /// By default, OpenAPI uses only the type name for schema references. This extension method changes 
+    /// the behavior to use the full type name (namespace + type name) to ensure unique schema IDs.
+    /// </remarks>
+    public static OpenApiOptions UseFullTypeNameSchemaIds(this OpenApiOptions options)
+    {
+        ArgumentNullException.ThrowIfNull(options);
+
+        options.CreateSchemaReferenceId = (jsonTypeInfo) =>
+        {
+            // Get the full type name (including namespace) for the schema ID
+            var fullName = jsonTypeInfo.Type.FullName;
+            
+            // Replace + with . for nested types to make the schema ID more readable
+            return fullName?.Replace('+', '.');
+        };
+
+        return options;
+    }
+
 }
 
 #endif

src/TinyHelpers.AspNetCore/README.md

@@ -73,6 +73,17 @@ builder.Services.AddOpenApi(options =>
 });
 ```
 
+- `UseFullTypeNameSchemaIds()`: configures OpenAPI to use the full type name (including namespace) for schema reference IDs, helping to avoid naming collisions when multiple types have the same name:
+
+```csharp
+builder.Services.AddOpenApi(options =>
+{
+    options.UseFullTypeNameSchemaIds();
+});
+```
+
+This is particularly useful when you have multiple types with the same name in different namespaces. For example, if you have both `MyApp.Models.User` and `MyApp.DTOs.User`, the default behavior would create a single schema named "User", potentially causing conflicts. With `UseFullTypeNameSchemaIds()`, the schemas will be named "MyApp.Models.User" and "MyApp.DTOs.User" respectively.
+
 **Contribute**
 
 The project is constantly evolving. Contributions are welcome. Feel free to file issues and pull requests on the repo and we'll address them as we can.