Add GenerateEnumMappingDescription setting, RicoSuter/NSwag#1993

RicoSuter · Mar 29, 2019 · b6faffc · b6faffc
1 parent 06d8688
commit b6faffc
Show file tree

Hide file tree

Showing 3 changed files with 26 additions and 4 deletions.
diff --git a/src/NJsonSchema.Tests/Generation/EnumGenerationTests.cs b/src/NJsonSchema.Tests/Generation/EnumGenerationTests.cs
@@ -18,6 +18,9 @@ public class Foo
             public Bar Bar2 { get; set; }
         }
 
+        /// <summary>
+        /// Foo bar.
+        /// </summary>
         public enum Bar
         {
             A = 0,
@@ -34,7 +37,8 @@ public async Task When_property_is_integer_enum_then_schema_has_enum()
             //// Act
             var schema = await JsonSchema4.FromTypeAsync<Foo>(new JsonSchemaGeneratorSettings
             {
-                DefaultEnumHandling = EnumHandling.Integer
+                DefaultEnumHandling = EnumHandling.Integer,
+                GenerateEnumMappingDescription = true
             });
             var data = schema.ToJson();
 
@@ -44,6 +48,9 @@ public async Task When_property_is_integer_enum_then_schema_has_enum()
             Assert.Equal(0, schema.Properties["Bar"].ActualTypeSchema.Enumeration.ElementAt(0));
             Assert.Equal(5, schema.Properties["Bar"].ActualTypeSchema.Enumeration.ElementAt(1));
             Assert.Equal(6, schema.Properties["Bar"].ActualTypeSchema.Enumeration.ElementAt(2));
+
+            Assert.Contains("Foo bar.", schema.Properties["Bar"].ActualTypeSchema.Description); // option is enabled
+            Assert.Contains("5 = B", schema.Properties["Bar"].ActualTypeSchema.Description); // option is enabled
         }
 
         [Fact]
@@ -63,6 +70,8 @@ public async Task When_string_and_integer_enum_used_then_two_refs_are_generated(
             Assert.NotNull(schema.Properties["Bar"].ActualTypeSchema);
             Assert.NotNull(schema.Properties["Bar2"].ActualTypeSchema); // must not be a reference but second enum declaration
             Assert.NotEqual(schema.Properties["Bar"].ActualTypeSchema, schema.Properties["Bar2"].ActualTypeSchema);
+
+            Assert.DoesNotContain("5 = B", schema.Properties["Bar"].ActualTypeSchema.Description); // option is not enabled
         }
 
         [Fact]
@@ -74,15 +83,19 @@ public async Task When_property_is_string_enum_then_schema_has_enum()
             //// Act
             var schema = await JsonSchema4.FromTypeAsync<Foo>(new JsonSchemaGeneratorSettings
             {
-                DefaultEnumHandling = EnumHandling.String
+                DefaultEnumHandling = EnumHandling.String,
+                GenerateEnumMappingDescription = true
             });
+            var data = schema.ToJson();
 
             //// Assert
             Assert.Equal(JsonObjectType.String, schema.Properties["Bar"].ActualTypeSchema.Type);
             Assert.Equal(3, schema.Properties["Bar"].ActualTypeSchema.Enumeration.Count);
             Assert.Equal("A", schema.Properties["Bar"].ActualTypeSchema.Enumeration.ElementAt(0));
             Assert.Equal("B", schema.Properties["Bar"].ActualTypeSchema.Enumeration.ElementAt(1));
             Assert.Equal("C", schema.Properties["Bar"].ActualTypeSchema.Enumeration.ElementAt(2));
+
+            Assert.DoesNotContain("=", schema.Properties["Bar"].ActualTypeSchema.Description); // string enums do not have mapping in description
         }
 
         [Fact]

diff --git a/src/NJsonSchema/Generation/JsonSchemaGenerator.cs b/src/NJsonSchema/Generation/JsonSchemaGenerator.cs
@@ -490,11 +490,11 @@ private async Task GenerateEnum<TSchemaType>(
                 schema.Reference = schemaResolver.GetSchema(type, isIntegerEnumeration);
             else if (schema.GetType() == typeof(JsonSchema4))
             {
-                LoadEnumerations(type, schema, typeDescription);
-
                 typeDescription.ApplyType(schema);
                 schema.Description = await type.GetXmlSummaryAsync().ConfigureAwait(false);
 
+                LoadEnumerations(type, schema, typeDescription);
+
                 schemaResolver.AddSchema(type, isIntegerEnumeration, schema);
             }
             else
@@ -905,6 +905,12 @@ private void LoadEnumerations(Type type, JsonSchema4 schema, JsonTypeDescription
 
                 schema.EnumerationNames.Add(enumName);
             }
+
+            if (typeDescription.Type == JsonObjectType.Integer && Settings.GenerateEnumMappingDescription)
+            {
+                schema.Description = (schema.Description + "\n\n" +
+                    string.Join("\n", schema.Enumeration.Select((e, i) => e + " = " + schema.EnumerationNames[i]))).Trim();
+            }
         }
 
         private async Task LoadPropertyOrFieldAsync(Newtonsoft.Json.Serialization.JsonProperty property, MemberInfo propertyInfo, Type parentType, JsonSchema4 parentSchema, JsonSchemaResolver schemaResolver)

diff --git a/src/NJsonSchema/Generation/JsonSchemaGeneratorSettings.cs b/src/NJsonSchema/Generation/JsonSchemaGeneratorSettings.cs
@@ -65,6 +65,9 @@ public JsonSchemaGeneratorSettings()
         /// defined on the object (otherwise allOf/oneOf with $ref is used, default: false).</summary>
         public bool AllowReferencesWithProperties { get; set; }
 
+        /// <summary>Gets or sets a value indicating whether to generate a description with number to enum name mappings (for integer enums only, default: false).</summary>
+        public bool GenerateEnumMappingDescription { get; set; }
+
         /// <summary>Gets or sets the schema type to generate (default: JsonSchema).</summary>
         public SchemaType SchemaType { get; set; }