Merge pull request #33 from jsheely/feat-description

SwaggerDescriptionAttribute
heldersepu · Dec 25, 2017 · 63f0899 · 63f0899
2 parents a6d9f2e + bfe1017
commit 63f0899
Show file tree

Hide file tree

Showing 7 changed files with 58 additions and 11 deletions.
diff --git a/Swagger.Net/Swagger.Net.csproj b/Swagger.Net/Swagger.Net.csproj
@@ -78,6 +78,7 @@
     <Compile Include="Swagger\Annotations\ApplySwaggerSchemaFilterAttributes.cs" />
     <Compile Include="Swagger\Annotations\ApplySwaggerOperationFilterAttributes.cs" />
     <Compile Include="Swagger\Annotations\ApplySwaggerOperationApiKey.cs" />
+    <Compile Include="Swagger\Annotations\SwaggerDescriptionAttribute.cs" />
     <Compile Include="Swagger\Annotations\SwaggerOperationAttribute.cs" />
     <Compile Include="Swagger\Annotations\SwaggerSchemaFilterAttribute.cs" />
     <Compile Include="Swagger\Annotations\SwaggerOperationFilterAttribute.cs" />

diff --git a/Swagger.Net/Swagger/Annotations/SwaggerDescriptionAttribute.cs b/Swagger.Net/Swagger/Annotations/SwaggerDescriptionAttribute.cs
@@ -0,0 +1,20 @@
+using System;
+using System.Collections.Generic;
+using System.Linq;
+using System.Text;
+using System.Threading.Tasks;
+
+namespace Swagger.Net.Swagger.Annotations
+{
+    public class SwaggerDescriptionAttribute: Attribute
+    {
+        public SwaggerDescriptionAttribute(string description = null, string summary = null)
+        {
+            Description = description;
+            Summary = summary;
+        }
+
+        public string Description { get; set; }
+        public string Summary { get; set; }
+    }
+}
diff --git a/Swagger.Net/Swagger/Extensions/ApiParameterDescriptionExtensions.cs b/Swagger.Net/Swagger/Extensions/ApiParameterDescriptionExtensions.cs
@@ -2,6 +2,7 @@
 using System.ComponentModel.DataAnnotations;
 using System.Linq;
 using System.Web.Http.Description;
+using Swagger.Net.Swagger.Annotations;
 
 namespace Swagger.Net.Swagger.Extensions
 {
@@ -12,9 +13,9 @@ public static RegularExpressionAttribute GetRegularExpressionAttribute(this ApiP
             return paramDesc.ParameterDescriptor.GetCustomAttributes<RegularExpressionAttribute>().FirstOrDefault();
         }
 
-        public static DescriptionAttribute GetDescriptionAttribute(this ApiParameterDescription paramDesc)
+        public static SwaggerDescriptionAttribute GetDescriptionAttribute(this ApiParameterDescription paramDesc)
         {
-            return paramDesc.ParameterDescriptor.GetCustomAttributes<DescriptionAttribute>().FirstOrDefault();
+            return paramDesc.ParameterDescriptor.GetCustomAttributes<SwaggerDescriptionAttribute>().FirstOrDefault();
         }
     }
 }
diff --git a/Swagger.Net/Swagger/Extensions/SchemaExtensions.cs b/Swagger.Net/Swagger/Extensions/SchemaExtensions.cs
@@ -1,6 +1,8 @@
 using Newtonsoft.Json.Serialization;
 using System;
 using System.ComponentModel.DataAnnotations;
+using System.Linq;
+using Swagger.Net.Swagger.Annotations;
 
 namespace Swagger.Net
 {
@@ -54,6 +56,17 @@ public static Schema WithValidationProperties(this Schema schema, JsonProperty j
             return schema;
         }
 
+        public static Schema WithDescriptionProperty(this Schema schema, JsonProperty jsonProperty)
+        {
+            var propInfo = jsonProperty.PropertyInfo();
+            if (propInfo == null)
+                return schema;
+
+            var attrib = propInfo.GetCustomAttributes(false).OfType<SwaggerDescriptionAttribute>().FirstOrDefault();
+            schema.description = attrib?.Description;
+            return schema;
+        }
+
         public static void PopulateFrom(this PartialSchema partialSchema, Schema schema)
         {
             if (schema == null) return;

diff --git a/Swagger.Net/Swagger/SchemaRegistry.cs b/Swagger.Net/Swagger/SchemaRegistry.cs
@@ -36,7 +36,7 @@ public SchemaRegistry(JsonSerializerSettings jsonSerializerSettings, SwaggerGene
 
         public Schema GetOrRegister(Type type, string typeName = null)
         {
-            var schema = CreateInlineSchema(type, typeName );
+            var schema = CreateInlineSchema(type, typeName);
 
             // Iterate outstanding work items (i.e. referenced types) and generate the corresponding definition
             while (_workItems.Any(entry => entry.Value.Schema == null && !entry.Value.InProgress))
@@ -205,21 +205,23 @@ public Schema CreateArraySchema(JsonArrayContract arrayContract, bool isWrapped
                 type = "array",
                 items = CreateInlineSchema(itemType)
             };
-            if( itemType.Namespace != "System" && itemType.Namespace != "Enum" )
+            if (itemType.Namespace != "System" && itemType.Namespace != "Enum")
             {
                 s.xml = new Xml { name = typeName ?? itemType.Name, wrapped = isWrapped };
             }
             return s;
         }
 
-        public Schema CreateObjectSchema(JsonObjectContract jsonContract, bool addXmlName = false )
+        public Schema CreateObjectSchema(JsonObjectContract jsonContract, bool addXmlName = false)
         {
             var properties = jsonContract.Properties
                 .Where(p => !p.Ignored)
                 .Where(p => !(_options.IgnoreObsoleteProperties && p.IsObsolete()))
                 .ToDictionary(
                     prop => prop.PropertyName,
-                    prop => CreateInlineSchema(prop.PropertyType).WithValidationProperties(prop)
+                    prop => CreateInlineSchema(prop.PropertyType)
+                        .WithValidationProperties(prop)
+                        .WithDescriptionProperty(prop)
                 );
 
             var required = jsonContract.Properties.Where(prop => prop.IsRequired())
@@ -232,7 +234,7 @@ public Schema CreateObjectSchema(JsonObjectContract jsonContract, bool addXmlNam
                 properties = properties,
                 type = "object"
             };
-            if( addXmlName )
+            if (addXmlName)
             {
                 s.xml = new Xml { name = jsonContract.UnderlyingType.Name };
             }

diff --git a/Swagger.Net/Swagger/SwaggerGenerator.cs b/Swagger.Net/Swagger/SwaggerGenerator.cs
@@ -7,6 +7,8 @@
 using System.Linq;
 using System.Net.Http;
 using System.Web.Http.Description;
+using System.Reflection;
+using Swagger.Net.Swagger.Annotations;
 
 namespace Swagger.Net
 {
@@ -52,7 +54,8 @@ public SwaggerDocument GetSwagger(string rootUrl, string apiVersion)
 
             var controllers = apiDescriptions
                 .GroupBy(x => x.ActionDescriptor.ControllerDescriptor)
-                .Select(x => new {
+                .Select(x => new
+                {
                     name = x.Key.ControllerName,
                     context = new ModelFilterContext(x.Key.ControllerType, null, null)
                 });
@@ -151,6 +154,9 @@ private Operation CreateOperation(ApiDescription apiDesc, SchemaRegistry schemaR
                 })
                  .ToList();
 
+            var description = apiDesc.ActionDescriptor.GetCustomAttributes<SwaggerDescriptionAttribute>()
+                .FirstOrDefault();
+
             var responses = new Dictionary<string, Response>();
             var responseType = apiDesc.ResponseType();
             if (responseType == null || responseType == typeof(void))
@@ -162,6 +168,8 @@ private Operation CreateOperation(ApiDescription apiDesc, SchemaRegistry schemaR
             {
                 tags = new[] { _options.GroupingKeySelector(apiDesc) },
                 operationId = this.GetUniqueFriendlyId(apiDesc, operationNames),
+                description = description?.Description,
+                summary = description?.Summary,
                 produces = apiDesc.Produces().ToList(),
                 consumes = apiDesc.Consumes().ToList(),
                 parameters = parameters.Any() ? parameters : null, // parameters can be null but not empty
@@ -208,10 +216,11 @@ private string GetParameterLocation(ApiDescription apiDesc, ApiParameterDescript
 
         private Parameter CreateParameter(string location, ApiParameterDescription paramDesc, SchemaRegistry schemaRegistry)
         {
+
             var parameter = new Parameter
             {
                 @in = location,
-                name = paramDesc.Name
+                name = paramDesc.Name,
             };
 
             if (paramDesc.ParameterDescriptor == null)

diff --git a/Tests/Swagger.Net.Dummy.Core/Controllers/SwaggerAnnotatedController.cs b/Tests/Swagger.Net.Dummy.Core/Controllers/SwaggerAnnotatedController.cs
@@ -6,6 +6,7 @@
 using System.Net;
 using System.Net.Http;
 using System.Web.Http;
+using Swagger.Net.Swagger.Annotations;
 
 namespace Swagger.Net.Dummy.Controllers
 {
@@ -40,7 +41,7 @@ public HttpResponseMessage Patch()
 
         [HttpPut]
         [SwaggerOperation("UpdateMessage", Tags = new[] { "messages" }, Schemes = new[] { "ws" })]
-        public void Put([Description("param description")]int id, Message message)
+        public void Put([SwaggerDescription("param description")]int id, Message message)
         {
             throw new NotImplementedException();
         }
@@ -56,7 +57,7 @@ public class Message2: Message { }
     [SwaggerSchemaFilter(typeof(AddMessageDefault))]
     public class Message
     {
-        [Description("param model description")]
+        [SwaggerDescription("param model description")]
         public string Title { get; set; }
         public string Content { get; set; }
     }