Merge pull request #2 from tennisi/lucasteles-swagger_schema

Lucasteles swagger schema

Author: mdementyev

README.md

@@ -54,6 +54,8 @@ To use the the [StronglyTypedId NuGet package](https://www.nuget.org/packages/St
 * [System.Text.Json](https://www.nuget.org/packages/System.Text.Json/) (optional, only required if [generating a System.Text `JsonConverter`](https://andrewlock.net/using-strongly-typed-entity-ids-to-avoid-primitive-obsession-part-2/#creating-a-custom-jsonconverter)). Note that in .NET Core apps, you will likely already reference this project via transitive dependencies.
 * [Dapper](https://www.nuget.org/packages/Dapper/) (optional, only required if [generating a type mapper](https://andrewlock.net/using-strongly-typed-entity-ids-to-avoid-primitive-obsession-part-3/#interfacing-with-external-system-using-strongly-typed-ids))
 * [EF Core](https://www.nuget.org/packages/Microsoft.EntityFrameworkCore) (optional, only required if [generating an EF Core ValueConverter](https://andrewlock.net/strongly-typed-ids-in-ef-core-using-strongly-typed-entity-ids-to-avoid-primitive-obsession-part-4/))
+* [Swagger Annotations](https://www.nuget.org/packages/Swashbuckle.AspNetCore.Annotations) (optional, only required if [generating an Swagger Schema Filter](#openapiswagger-specification)
+
 
 To install the packages, add the references to your _csproj_ file, for example by running
 
@@ -160,6 +162,18 @@ public partial struct OrderId { }
 public partial struct UserId { }
 ```
 
+## OpenApi/Swagger Specification
+
+If you wish to use an ID in your Swagger models and want to have schema and model sample reflecting the ID backingfield type you will need:
+- Install [Swagger Annotations](https://www.nuget.org/packages/Swashbuckle.AspNetCore.Annotations) `>=5.0.0` 
+- Enable annotation in swagger gen with `services.AddSwaggerGen(c => c.EnableAnnotations());`
+- Use the converter flag `StronglyTypedIdConverter.SwaggerSchemaFilter` on the ID decorator. eg:
+    ```csharp
+    [StronglyTypedId(
+        backingType: StronglyTypedIdBackingType.Int,
+        converters: StronglyTypedIdConverter.SwaggerSchemaFilter | StronglyTypedIdConverter.SystemTextJson)]
+    public partial struct UserId { }
+    ```
 
 ## Embedding the attributes in your project
 
@@ -253,4 +267,4 @@ The `struct`s you decorate with the `StronglyTypedId` attribute must be marked `
 
 `StronglyTypedId` wouldn't work if not for [AArnott's CodeGeneration.Roslyn](https://github.com/AArnott/CodeGeneration.Roslyn) library.
 
-The build process and general design of the library was modelled on the [RecordGenerator](https://github.com/amis92/RecordGenerator/blob/master/README.md) project, which is similar to this project, but can be used to generate immutable Record types.
+The build process and general design of the library was modelled on the [RecordGenerator](https://github.com/amis92/RecordGenerator/blob/master/README.md) project, which is similar to this project, but can be used to generate immutable Record types.

src/StronglyTypedIds.Attributes/StronglyTypedIdConverter.cs

@@ -46,5 +46,11 @@ public enum StronglyTypedIdConverter
         /// Creates a Dapper TypeHandler for converting to and from the type
         /// </summary>
         DapperTypeHandler = 32,
+
+        /// <summary>
+        /// Creates a Swagger SchemaFilter for OpenApi documentation
+        /// </summary>
+        SwaggerSchemaFilter = 64,
+
     }
 }

src/StronglyTypedIds/EmbeddedSources.cs

@@ -25,6 +25,7 @@ internal static class EmbeddedSources
             LoadEmbeddedResource("StronglyTypedIds.Templates.Guid.Guid_EfCoreValueConverter.cs"),
             LoadEmbeddedResource("StronglyTypedIds.Templates.Guid.Guid_DapperTypeHandler.cs"),
             LoadEmbeddedResource("StronglyTypedIds.Templates.Guid.Guid_IComparable.cs"),
+            LoadEmbeddedResource("StronglyTypedIds.Templates.Guid.Guid_SwaggerSchemaFilter.cs"),
             false
         );
 
@@ -37,6 +38,7 @@ internal static class EmbeddedSources
             LoadEmbeddedResource("StronglyTypedIds.Templates.Int.Int_EfCoreValueConverter.cs"),
             LoadEmbeddedResource("StronglyTypedIds.Templates.Int.Int_DapperTypeHandler.cs"),
             LoadEmbeddedResource("StronglyTypedIds.Templates.Int.Int_IComparable.cs"),
+            LoadEmbeddedResource("StronglyTypedIds.Templates.Int.Int_SwaggerSchemaFilter.cs"),
             false
         );
 
@@ -49,6 +51,7 @@ internal static class EmbeddedSources
             LoadEmbeddedResource("StronglyTypedIds.Templates.Long.Long_EfCoreValueConverter.cs"),
             LoadEmbeddedResource("StronglyTypedIds.Templates.Long.Long_DapperTypeHandler.cs"),
             LoadEmbeddedResource("StronglyTypedIds.Templates.Long.Long_IComparable.cs"),
+            LoadEmbeddedResource("StronglyTypedIds.Templates.Long.Long_SwaggerSchemaFilter.cs"),
             false
         );
 
@@ -61,6 +64,7 @@ internal static class EmbeddedSources
             LoadEmbeddedResource("StronglyTypedIds.Templates.String.String_EfCoreValueConverter.cs"),
             LoadEmbeddedResource("StronglyTypedIds.Templates.String.String_DapperTypeHandler.cs"),
             LoadEmbeddedResource("StronglyTypedIds.Templates.String.String_IComparable.cs"),
+            LoadEmbeddedResource("StronglyTypedIds.Templates.String.String_SwaggerSchemaFilter.cs"),
             false
         );
 
@@ -73,6 +77,7 @@ internal static class EmbeddedSources
             LoadEmbeddedResource("StronglyTypedIds.Templates.NullableString.NullableString_EfCoreValueConverter.cs"),
             LoadEmbeddedResource("StronglyTypedIds.Templates.NullableString.NullableString_DapperTypeHandler.cs"),
             LoadEmbeddedResource("StronglyTypedIds.Templates.NullableString.NullableString_IComparable.cs"),
+            LoadEmbeddedResource("StronglyTypedIds.Templates.NullableString.NullableString_SwaggerSchemaFilter.cs"),
             true
         );
 
@@ -85,12 +90,14 @@ internal static class EmbeddedSources
             LoadEmbeddedResource("StronglyTypedIds.Templates.NewId.NewId_EfCoreValueConverter.cs"),
             LoadEmbeddedResource("StronglyTypedIds.Templates.NewId.NewId_DapperTypeHandler.cs"),
             LoadEmbeddedResource("StronglyTypedIds.Templates.NewId.NewId_IComparable.cs"),
+            LoadEmbeddedResource("StronglyTypedIds.Templates.NewId.NewId_SwaggerSchemaFilter.cs"),
             false
         );
 
         internal const string TypeConverterAttributeSource = "    [System.ComponentModel.TypeConverter(typeof(TESTIDTypeConverter))]";
         internal const string NewtonsoftJsonAttributeSource = "    [Newtonsoft.Json.JsonConverter(typeof(TESTIDNewtonsoftJsonConverter))]";
         internal const string SystemTextJsonAttributeSource = "    [System.Text.Json.Serialization.JsonConverter(typeof(TESTIDSystemTextJsonConverter))]";
+        internal const string SwaggerSchemaFilterAttributeSource = "    [Swashbuckle.AspNetCore.Annotations.SwaggerSchemaFilter(typeof(TESTIDSchemaFilter))]";
 
         internal static string LoadEmbeddedResource(string resourceName)
         {
@@ -108,6 +115,7 @@ internal static string LoadEmbeddedResource(string resourceName)
 
         public readonly struct ResourceCollection
         {
+            public string SwaggerSchemaFilter { get; }
             public string Header { get; }
             public bool NullableEnable { get; }
             public string BaseId { get; }
@@ -127,8 +135,10 @@ public ResourceCollection(
                 string efCoreValueConverter,
                 string dapperTypeHandler,
                 string comparable,
+                string swaggerSchemaFilter,
                 bool nullableEnable)
             {
+                SwaggerSchemaFilter = swaggerSchemaFilter;
                 BaseId = baseId;
                 Newtonsoft = newtonsoft;
                 SystemTextJson = systemTextJson;

src/StronglyTypedIds/SourceGenerationHelper.cs

@@ -64,6 +64,7 @@ static string CreateId(
 
             var hasNamespace = !string.IsNullOrEmpty(idNamespace);
 
+            var useSchemaFilter = converters.IsSet(StronglyTypedIdConverter.SwaggerSchemaFilter);
             var useTypeConverter = converters.IsSet(StronglyTypedIdConverter.TypeConverter);
             var useNewtonsoftJson = converters.IsSet(StronglyTypedIdConverter.NewtonsoftJson);
             var useSystemTextJson = converters.IsSet(StronglyTypedIdConverter.SystemTextJson);
@@ -122,6 +123,12 @@ static string CreateId(
                 sb.AppendLine(EmbeddedSources.TypeConverterAttributeSource);
             }
 
+            if (useSchemaFilter)
+            {
+                sb.AppendLine(EmbeddedSources.SwaggerSchemaFilterAttributeSource);
+            }
+
+
             sb.Append(resources.BaseId);
             ReplaceInterfaces(sb, useIEquatable, useIComparable);
 
@@ -157,6 +164,11 @@ static string CreateId(
                 sb.AppendLine(resources.SystemTextJson);
             }
 
+            if (useSchemaFilter)
+            {
+                sb.AppendLine(resources.SwaggerSchemaFilter);
+            }
+
             sb.Replace("TESTID", idName);
             sb.AppendLine(@"    }");
 

src/StronglyTypedIds/Templates/Guid/Guid_SwaggerSchemaFilter.cs

@@ -0,0 +1,13 @@
+
+        class TESTIDSchemaFilter : Swashbuckle.AspNetCore.SwaggerGen.ISchemaFilter
+        {
+            public void Apply(Microsoft.OpenApi.Models.OpenApiSchema schema, Swashbuckle.AspNetCore.SwaggerGen.SchemaFilterContext context)
+            {
+                var idSchema = new Microsoft.OpenApi.Models.OpenApiSchema {Type = "string", Format = "uuid"};
+                schema.Type = idSchema.Type;
+                schema.Format = idSchema.Format;
+                schema.Example = idSchema.Example;
+                schema.Default = idSchema.Default;
+                schema.Properties = idSchema.Properties;
+            }
+        }

src/StronglyTypedIds/Templates/Int/Int_SwaggerSchemaFilter.cs

@@ -0,0 +1,13 @@
+
+        class TESTIDSchemaFilter : Swashbuckle.AspNetCore.SwaggerGen.ISchemaFilter
+        {
+            public void Apply(Microsoft.OpenApi.Models.OpenApiSchema schema, Swashbuckle.AspNetCore.SwaggerGen.SchemaFilterContext context)
+            {
+                var idSchema = new Microsoft.OpenApi.Models.OpenApiSchema {Type = "integer", Format = "int32"};
+                schema.Type = idSchema.Type;
+                schema.Format = idSchema.Format;
+                schema.Example = idSchema.Example;
+                schema.Default = idSchema.Default;
+                schema.Properties = idSchema.Properties;
+            }
+        }

src/StronglyTypedIds/Templates/Long/Long_SwaggerSchemaFilter.cs

@@ -0,0 +1,13 @@
+
+        class TESTIDSchemaFilter : Swashbuckle.AspNetCore.SwaggerGen.ISchemaFilter
+        {
+            public void Apply(Microsoft.OpenApi.Models.OpenApiSchema schema, Swashbuckle.AspNetCore.SwaggerGen.SchemaFilterContext context)
+            {
+                var idSchema = new Microsoft.OpenApi.Models.OpenApiSchema {Type = "integer", Format = "int64"};
+                schema.Type = idSchema.Type;
+                schema.Format = idSchema.Format;
+                schema.Example = idSchema.Example;
+                schema.Default = idSchema.Default;
+                schema.Properties = idSchema.Properties;
+            }
+        }

src/StronglyTypedIds/Templates/NewId/NewId_SwaggerSchemaFilter.cs

@@ -0,0 +1,13 @@
+
+        class TESTIDSchemaFilter : Swashbuckle.AspNetCore.SwaggerGen.ISchemaFilter
+        {
+            public void Apply(Microsoft.OpenApi.Models.OpenApiSchema schema, Swashbuckle.AspNetCore.SwaggerGen.SchemaFilterContext context)
+            {
+                var idSchema = new Microsoft.OpenApi.Models.OpenApiSchema {Type = "string", Format = "uuid"};
+                schema.Type = idSchema.Type;
+                schema.Format = idSchema.Format;
+                schema.Example = idSchema.Example;
+                schema.Default = idSchema.Default;
+                schema.Properties = idSchema.Properties;
+            }
+        }

src/StronglyTypedIds/Templates/NullableString/NullableString_SwaggerSchemaFilter.cs

@@ -0,0 +1,14 @@
+
+        class TESTIDSchemaFilter : Swashbuckle.AspNetCore.SwaggerGen.ISchemaFilter
+        {
+            public void Apply(Microsoft.OpenApi.Models.OpenApiSchema schema, Swashbuckle.AspNetCore.SwaggerGen.SchemaFilterContext context)
+            {
+                var idSchema = new Microsoft.OpenApi.Models.OpenApiSchema {Type = "string", Format = ""};
+                schema.Type = idSchema.Type;
+                schema.Format = idSchema.Format;
+                schema.Example = idSchema.Example;
+                schema.Default = idSchema.Default;
+                schema.Properties = idSchema.Properties;
+                schema.Nullable = true;
+            }
+        }

src/StronglyTypedIds/Templates/String/String_SwaggerSchemaFilter.cs

@@ -0,0 +1,14 @@
+
+        class TESTIDSchemaFilter : Swashbuckle.AspNetCore.SwaggerGen.ISchemaFilter
+        {
+            public void Apply(Microsoft.OpenApi.Models.OpenApiSchema schema, Swashbuckle.AspNetCore.SwaggerGen.SchemaFilterContext context)
+            {
+                var idSchema = new Microsoft.OpenApi.Models.OpenApiSchema {Type = "string", Format = ""};
+                schema.Type = idSchema.Type;
+                schema.Format = idSchema.Format;
+                schema.Example = idSchema.Example;
+                schema.Default = idSchema.Default;
+                schema.Properties = idSchema.Properties;
+                schema.Nullable = false;
+            }
+        }