improved readme

Author: foresightyj

README.md

@@ -1,23 +1,75 @@
-# ValueOf.Extensions
+ValueOf.Extensions
+==================
 
-This library contains a set of adapters/utilities you might need when using the
-popular [ValueOf](https://github.com/mcintyre321/ValueOf) library. It helps you in these areas:
+This library contains a set of adapters/utilities you might need when using the popular [ValueOf](https://github.com/mcintyre321/ValueOf) library. 
 
-1. JSON serialization
-2. Dapper/EF.Core
-3. Swagger/OpenAPI
+Below is a list of features supported in each package:
 
-## Feature 1: JSON serialization adapter for System.Text.Json & Newtonsoft.Json
+# Package: ValueOf.Extensions
 
-For System.Text.JSON, you will need an adapter (see [the reason]( https://github.com/dotnet/runtime/issues/38812 ))
+## System.Text.Json JSON serialization/deserialization with `ValueOfJsonAdapterFactory`
 
-```csharp
-    var options = new JsonSerializerOptions();
-    options.Converters.Add(new TypeConverterJsonAdapterFactory());
-    System.Text.Json.JsonSerializer.Serialize(_dut, options);
+```cs
+var options = new JsonSerializerOptions
+{
+    Converters = { new ValueOfJsonAdapterFactory() },
+};
 ```
 
-For Newtonsoft.Json, it is automatic.
+or in ASP.NET Core:
+
+```cs
+builder.Services.AddControllers().AddJsonOptions(options =>
+{
+    options.JsonSerializerOptions.Converters.Add(new ValueOfJsonAdapterFactory());
+});
+```
+
+## TypeConverter with `ValueOfTypeConverter<TU, T>`
+
+This is needed if you want to be able to parse a `ValueOf` type from strings. Typically you'll need it when you want to bind API parameters e.g.  `[FromRoute] UserId id` & `[FromQuery] EmailAddress email` in ASP.NET Core.
+
+You can use this provided extension method to add all `ValueOf` types collectively.
+
+```cs
+    ValueOfTypeExtensions.ConfigureValueOfTypeConverters(typeof(UserId).Assembly);
+```
+
+# Package: ValueOf.Extensions.NewtonsoftJson
+
+If you are using Newtonsoft.JSON, this package fixes serialization/deserialization with a custom JsonConverter `ValueOfNewtonsoftConverter`.
+
+```cs
+var settings = new JsonSerializerSettings
+{
+    Converters = [new ValueOfNewtonsoftConverter()],
+};
+```
+
+# Package: ValueOf.Extensions.Dapper
+
+With this package, you can have your column be of `ValueOf` types. 
+
+You can use the provided extension method to register all `ValueOfDapperTypeHandler`s from assemblies with ease:
+
+```cs
+ValueOfDapperExtensions.ConfigureValueOfDapperTypeHandlers(typeof(UserId).Assembly);
+```
+
+# Package: ValueOf.Extensions.Swagger
+
+If you `ValueOf`, swagger will still consider a `ValueOf` type a complex type instead of a simple type. This package helps you fix that by picking the most suitable `type` & `format` based on the underlying type.
+
+This extension method helps you map all your `ValueOf` types to the correct schema.
+```cs
+    opts.MapValueOfTypesInAssemblies(null, typeof(EmailAddress).Assembly);
+```
+
+If `type` & `format` picked for you doesn't suit your needs, you can use the `SwaggerTypeMap? typeMapOverride` parameter in `MapValueOfTypesInAssemblies` to customize.
+
+NOTE: currently I only handled `Swashbuckle.AspNetCore`. Let me know or send me PR if you want integration for other Swagger/Open API solutions.
+
+# References
 
 see [Document a System.Text.Json TypeConverter to JsonConverter Adapter · Issue #1761 · dotnet/runtime]( https://github.com/dotnet/runtime/issues/1761 )
 

ValueOf.Extensions.Examples/Program.cs

@@ -31,7 +31,7 @@
     opts.IgnoreObsoleteActions();
     opts.IgnoreObsoleteProperties();
     opts.UseAllOfForInheritance();
-    opts.MapValueOfTypesInAssemblies(typeof(EmailAddress).Assembly);
+    opts.MapValueOfTypesInAssemblies(null, typeof(EmailAddress).Assembly);
 });
 
 builder.Services.AddDbContext<DemoDbContext>(opts => { opts.UseSqlite("Data Source=demo.db"); });
@@ -51,4 +51,6 @@
 
 app.Run();
 
-public partial class Program { }
+public partial class Program
+{
+}

ValueOf.Extensions.SwashbuckleSwagger/SwaggerValueOfExtensions.cs

@@ -75,13 +75,16 @@ public static void MapValueOfTypes(this SwaggerGenOptions opts, IEnumerable<Type
             }
         }
 
-        public static void MapValueOfTypesInAssemblies(this SwaggerGenOptions opts, params Assembly[] assemblies)
+        public static void MapValueOfTypesInAssemblies(this SwaggerGenOptions opts,
+            SwaggerTypeMap? typeMapOverride = null,
+            params Assembly[] assemblies
+        )
         {
             if (opts == null) throw new ArgumentNullException(nameof(opts));
             var valueOfTypes = from a in assemblies
                 from t in a.DefinedTypes.Select(t => t.AsType())
                 select t;
-            MapValueOfTypes(opts, valueOfTypes);
+            MapValueOfTypes(opts, valueOfTypes, typeMapOverride);
         }
     }
 }

ValueOf.Extensions/BuiltinTypeParser.cs

@@ -2,7 +2,7 @@
 
 namespace ValueOf.Extensions
 {
-    public static class BuiltinTypeParser
+    internal static class BuiltinTypeParser
     {
         private static class Cache<T>
         {