Trying to fix the output SwaggerGen types generically.

Harvzor.Optional.sln

@@ -30,6 +30,10 @@ Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "Harvzor.Optional.SystemText
 EndProject
 Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "Harvzor.Optional.JsonConverter.BaseTests", "tests\Harvzor.Optional.JsonConverter.BaseTests\Harvzor.Optional.JsonConverter.BaseTests.csproj", "{4257F779-067E-4EF8-9B56-DACCBA996357}"
 EndProject
+Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "Harvzor.Optional.Swashbuckle", "src\Harvzor.Optional.Swashbuckle\Harvzor.Optional.Swashbuckle.csproj", "{3BFA9880-A29C-444D-9F94-633FE0901CFE}"
+EndProject
+Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "Harvzor.Optional.Swashbuckle.Tests", "tests\Harvzor.Optional.Swashbuckle.Tests\Harvzor.Optional.Swashbuckle.Tests.csproj", "{171F8BB6-1167-4553-9E4B-BEC33E75DC4F}"
+EndProject
 Global
 	GlobalSection(SolutionConfigurationPlatforms) = preSolution
 		Debug|Any CPU = Debug|Any CPU
@@ -84,6 +88,14 @@ Global
 		{4257F779-067E-4EF8-9B56-DACCBA996357}.Debug|Any CPU.Build.0 = Debug|Any CPU
 		{4257F779-067E-4EF8-9B56-DACCBA996357}.Release|Any CPU.ActiveCfg = Release|Any CPU
 		{4257F779-067E-4EF8-9B56-DACCBA996357}.Release|Any CPU.Build.0 = Release|Any CPU
+		{3BFA9880-A29C-444D-9F94-633FE0901CFE}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{3BFA9880-A29C-444D-9F94-633FE0901CFE}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{3BFA9880-A29C-444D-9F94-633FE0901CFE}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{3BFA9880-A29C-444D-9F94-633FE0901CFE}.Release|Any CPU.Build.0 = Release|Any CPU
+		{171F8BB6-1167-4553-9E4B-BEC33E75DC4F}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{171F8BB6-1167-4553-9E4B-BEC33E75DC4F}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{171F8BB6-1167-4553-9E4B-BEC33E75DC4F}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{171F8BB6-1167-4553-9E4B-BEC33E75DC4F}.Release|Any CPU.Build.0 = Release|Any CPU
 	EndGlobalSection
 	GlobalSection(NestedProjects) = preSolution
 		{9ED9BB37-3250-4DF0-8224-FE86BAA2859A} = {0DC0E672-7784-4D81-8A18-C415472AC595}
@@ -98,5 +110,7 @@ Global
 		{22F65313-6A49-408E-8603-DE267698FCC2} = {A8A8C7B4-D30A-49F8-8F0F-D2CDB88EDE53}
 		{990ADC1B-BAAB-4170-B17F-BBED94FDD6DB} = {A8A8C7B4-D30A-49F8-8F0F-D2CDB88EDE53}
 		{4257F779-067E-4EF8-9B56-DACCBA996357} = {A8A8C7B4-D30A-49F8-8F0F-D2CDB88EDE53}
+		{3BFA9880-A29C-444D-9F94-633FE0901CFE} = {0DC0E672-7784-4D81-8A18-C415472AC595}
+		{171F8BB6-1167-4553-9E4B-BEC33E75DC4F} = {A8A8C7B4-D30A-49F8-8F0F-D2CDB88EDE53}
 	EndGlobalSection
 EndGlobal

README.md

@@ -7,6 +7,7 @@
 | Harvzor.Optional                | [![NuGet](https://img.shields.io/nuget/v/Harvzor.Optional)](https://www.nuget.org/packages/Harvzor.Optional/)                               |
 | Harvzor.Optional.SystemTextJson | [![NuGet](https://img.shields.io/nuget/v/Harvzor.Optional.SystemTextJson)](https://www.nuget.org/packages/Harvzor.Optional.SystemTextJson/) |
 | Harvzor.Optional.NewtonsoftJson | [![NuGet](https://img.shields.io/nuget/v/Harvzor.Optional.NewtonsoftJson)](https://www.nuget.org/packages/Harvzor.Optional.NewtonsoftJson/) |
+| Harvzor.Optional.Swashbuckle    | [![NuGet](https://img.shields.io/nuget/v/Harvzor.Optional.Swashbuckle)](https://www.nuget.org/packages/Harvzor.Optional.Swashbuckle/)       |
 
 ## The problem
 
@@ -135,9 +136,97 @@ services
     });
 ```
 
-#### Swagger support
+### Swagger support
 
-If you're using Swashbuckle Swagger, you'll also need to tell it how your types should look:
+#### Harvzor.Optional.Swashbuckle
+
+> **Warning**
+> This package is experimental.
+
+Swashbuckle SwaggerGen doesn't know how to handle `Optional<T>` and will attempt to generate complicated objects to express all the properties, for a simple class like:
+
+```csharp
+public class Foo
+{
+    public Optional<int> OptionalInt { get; set; }
+}
+```
+
+This ends up being generated like:
+
+![broken-swagger-docs.png](.github/docs/broken-swagger-docs.png)
+
+Instead we want SwaggerGen to treat `Optional<T>` as the generic type `T`. To handle doing this, add this:
+
+```csharp
+using Harvzor.Optional.Swashbuckle;
+
+services
+    .AddSwaggerGen(options =>
+    {
+        // The assembly you pass in should include your controllers and perhaps even your DTOs.
+        options.FixOptionalMappings(Assembly.GetExecutingAssembly());
+    });
+```
+
+This results in the correct OpenAPI spec:
+
+![fixed-swagger-docs.png](.github/docs/fixed-swagger-docs.png)
+
+This will:
+
+- ensure that all basic types like `Optional<string>` are mapped to the `string` type in the OpenAPI schema
+- try to treat complex objects such as `Optional<MyType>` as the underlying generic type `MyType`
+
+This doesn't work in all cases though, for example, with `Optional<Version>`, we want it to be treated as a `string` type and not as a `Version`, so this must be added:
+
+```csharp
+using Harvzor.Optional.Swashbuckle;
+
+// Add your custom mappings first:
+options.MapType<Optional<Version>>(() => new OpenApiSchema()
+{
+    Type = "string"
+});
+
+options.FixOptionalMappings(Assembly.GetExecutingAssembly());
+```
+
+Alternatively, if you don't want to call `FixOptionalMappings(params Assembly[] assemblies)` which automagically finds any references to `Optional<T>` in your assembly, you can just directly feed it `Optional<T>` types that you know are used in your controllers:
+
+```csharp
+using Harvzor.Optional.Swashbuckle;
+
+options
+    .FixOptionalMappingForType<Optional<Foo>>()
+    .FixOptionalMappingForType<Optional<Bar>>()
+    .FixOptionalMappingForType<Optional<int>>();
+```
+
+##### Known caveats
+
+- `FixOptionalMappings(params Assembly[] assemblies)` does not work with minimal APIs as it searches for `Optional<T>` references on parameters and properties of any classes that implement controller methods, and then maps those `Optional<T>` types to their generic type `T`
+- `Optional<T>` doesn't work with query parameters
+  - You can't have the following:
+    ```csharp
+    [HttpGet]
+    public string Get([FromQuery] Optional<string> foo)
+    {
+        return foo;
+    }
+    ```
+  - This is because of the following issue: https://github.com/domaindrivendev/Swashbuckle.AspNetCore/issues/2226
+
+##### Improvements
+
+This package could be improved if these issues are ever resolved:
+
+- https://github.com/domaindrivendev/Swashbuckle.AspNetCore/issues/1810
+- https://github.com/domaindrivendev/Swashbuckle.AspNetCore/issues/2359
+
+#### Manual Swagger support
+
+If you're using `Swashbuckle.AspNetCore.SwaggerGen` but don't want to use `Harvzor.Optional.Swashbuckle`, you can also manually tell it how your types should look. Here are some basic types mapped:
 
 ```csharp
 services.AddSwaggerGen(options =>
@@ -149,30 +238,75 @@ services.AddSwaggerGen(options =>
 
     options.MapType<Optional<int>>(() => new OpenApiSchema
     {
-        Type = "integer"
+        Type = "integer",
+        Format = "int32"
     });
 
     options.MapType<Optional<float>>(() => new OpenApiSchema
     {
-        Type = "number"
+        Type = "number",
+        Format = "float"
     });
 
     options.MapType<Optional<double>>(() => new OpenApiSchema
     {
-        Type = "number"
+        Type = "number",
+        Format = "double"
     });
 
     options.MapType<Optional<bool>>(() => new OpenApiSchema
     {
         Type = "boolean"
     });
 
-    // todo: array, object?
+    options.MapType<Optional<DateTime>>(() => new OpenApiSchema
+    {
+        Type = "string",
+        Format = "date-time"
+    });
+
+    // IEnumerables:
+    options.MapType<Optional<IEnumerable<int>>>(() => new OpenApiSchema
+    {
+        Type = "array",
+        Items = new OpenApiSchema
+        {
+            Type = "integer",
+            Format = "int32"
+        }
+    });
 });
 ```
 
 You can see what basic types are available here: https://swagger.io/docs/specification/data-models/data-types/
 
+However, handling custom objects such as `Optional<MyObject>` is quite complicated and not recommended, however, here's how to do it anyway:
+
+```csharp
+// Rewrite the mapping so it's an object reference:
+options.MapType<Optional<MyObject>>(() => new OpenApiSchema
+{
+    Type = "object",
+    Format = format,
+    Reference = new OpenApiReference
+    {
+        Id = nameof(MyObject),
+        Type = ReferenceType.Schema,
+    }
+});
+
+// Now add `MyObject` to the schema repisitory so the mapping actually points somewhere:
+options.DocumentFilter<GenerateSchemaFor<MyObject>>();
+
+private class GenerateSchemaFor<T> : IDocumentFilter where T : class
+{
+    public void Apply(OpenApiDocument swaggerDoc, DocumentFilterContext context)
+    {
+          context.SchemaGenerator.GenerateSchema(typeof(T), context.SchemaRepository);
+    }
+}
+```
+
 ## Use case: JSON Merge PATCH
 
 ... need docs ...
@@ -198,3 +332,5 @@ docker-compose run --rm push-nuget --api-key {key}
 
 - https://stackoverflow.com/questions/63418549/custom-json-serializer-for-optional-property-with-system-text-json
 - https://stackoverflow.com/questions/12522000/optionally-serialize-a-property-based-on-its-runtime-value
+- Optional in Swagger definition and how to handle generic types: https://github.com/domaindrivendev/Swashbuckle.AspNetCore/issues/2359
+  - ISchemaGenerator: https://github.com/domaindrivendev/Swashbuckle.AspNetCore/issues/2333#issuecomment-1035695675

examples/Harvzor.Optional.NewtonsoftJson.WebExample/Harvzor.Optional.NewtonsoftJson.WebExample.csproj

@@ -11,6 +11,7 @@
 
     <ItemGroup>
       <ProjectReference Include="..\..\src\Harvzor.Optional.NewtonsoftJson\Harvzor.Optional.NewtonsoftJson.csproj" />
+      <ProjectReference Include="..\..\src\Harvzor.Optional.Swashbuckle\Harvzor.Optional.Swashbuckle.csproj" />
     </ItemGroup>
 
     <ItemGroup>

examples/Harvzor.Optional.NewtonsoftJson.WebExample/Program.cs

@@ -1,18 +1,26 @@
+using System.Reflection;
 using Harvzor.Optional;
 using Harvzor.Optional.NewtonsoftJson;
 using Microsoft.AspNetCore.Mvc;
-using Microsoft.OpenApi.Models;
+using Harvzor.Optional.Swashbuckle;
 
 var builder = WebApplication.CreateBuilder(args);
 
 builder.Services
-    .AddEndpointsApiExplorer()
     .AddSwaggerGen(options =>
     {
-        options.MapType<Optional<string>>(() => new OpenApiSchema
-        {
-            Type = "string"
-        });
+        // Map types manually without Harvzor.Optional.Swashbuckle:
+        // options.MapType<Optional<string?>>(() => new OpenApiSchema
+        // {
+        //     Type = "string"
+        // });
+
+        // Auto fixes mappings:
+        options.FixOptionalMappings(Assembly.GetExecutingAssembly());
+
+        // Alternatively, specify specific types that should be fixed:
+        // options
+        //     .FixOptionalMappingForType<Optional<string>>();
     })
     .AddSwaggerGenNewtonsoftSupport();
 
@@ -50,16 +58,19 @@ public string Get()
     }
 
     [HttpPost]
-    public string Post(Foo foo)
+    public Foo Post(Foo foo)
     {
-        if (foo.OptionalString.IsDefined)
-            return $"You're value is \"{foo.OptionalString.Value ?? "null"}\".";
-
-        return "You sent nothing.";
+        Console.WriteLine(
+            foo.OptionalString.IsDefined
+                ? $"You sent: {(foo.OptionalString.Value == null ? "null" : $"\"{foo.OptionalString.Value}\"")}"
+                : "You sent nothing!"
+        );
+
+        return foo;
     }
 }
 
-public record Foo
+public class Foo
 {
     public Optional<string?> OptionalString { get; set; }
 }

examples/Harvzor.Optional.SystemTextJson.WebExample/Harvzor.Optional.SystemTextJson.WebExample.csproj

@@ -10,6 +10,7 @@
     </PropertyGroup>
 
     <ItemGroup>
+      <ProjectReference Include="..\..\src\Harvzor.Optional.Swashbuckle\Harvzor.Optional.Swashbuckle.csproj" />
       <ProjectReference Include="..\..\src\Harvzor.Optional.SystemTextJson\Harvzor.Optional.SystemTextJson.csproj" />
     </ItemGroup>