Merge pull request #1629 from mattfrear/feature/1628-xml-param-examples

Add examples to XML params

.gitignore

@@ -11,4 +11,5 @@ artifacts/
 .DS_Store
 Thumbs.db
 test/WebSites/CliExample/wwwroot/api-docs/v1/*.json
-test/WebSites/CliExampleWithFactory/wwwroot/api-docs/v1/*.json
+test/WebSites/CliExampleWithFactory/wwwroot/api-docs/v1/*.json
+*ncrunch*

README.md

@@ -460,13 +460,14 @@ To enhance the generated docs with human-friendly descriptions, you can annotate
     }
     ```
 
-3. Annotate your actions with summary, remarks and response tags:
+3. Annotate your actions with summary, remarks, param and response tags:
 
     ```csharp
     /// <summary>
     /// Retrieves a specific product by unique id
     /// </summary>
     /// <remarks>Awesomeness!</remarks>
+    /// <param name="id" example="123">The product id</param>
     /// <response code="200">Product created</response>
     /// <response code="400">Product has missing/invalid values</response>
     /// <response code="500">Oops! Can't create your product right now</response>

src/Swashbuckle.AspNetCore.SwaggerGen/XmlComments/XmlCommentsSchemaFilter.cs

@@ -80,6 +80,12 @@ private void ApplyParamTags(OpenApiSchema schema, ParameterInfo parameterInfo)
             if (paramNode != null)
             {
                 schema.Description = XmlCommentsTextHelper.Humanize(paramNode.InnerXml);
+
+                var example = paramNode.GetAttribute("example", "");
+                if (!string.IsNullOrEmpty(example))
+                {
+                    schema.Example = ConvertToOpenApiType(parameterInfo.ParameterType, schema, example);
+                }
             }
         }
 

test/Swashbuckle.AspNetCore.SwaggerGen.Test/Fixtures/FakeControllerWithXmlComments.cs

@@ -1,4 +1,7 @@
-namespace Swashbuckle.AspNetCore.SwaggerGen.Test
+using Swashbuckle.AspNetCore.TestSupport;
+using System;
+
+namespace Swashbuckle.AspNetCore.SwaggerGen.Test
 {
     /// <summary>
     /// Summary for FakeControllerWithXmlComments
@@ -24,5 +27,26 @@ public void ActionWithParamTags(string param1, string param2)
         /// <response code="400">Description for 400 response</response>
         public void ActionWithResponseTags()
         { }
+
+        /// <param name="boolParam" example="true"></param>
+        /// <param name="intParam" example="27"></param>
+        /// <param name="longParam" example="4294967296"></param>
+        /// <param name="floatParam" example="1.23"></param>
+        /// <param name="doubleParam" example="1.25"></param>
+        /// <param name="enumParam" example="2"></param>
+        /// <param name="guidParam" example="1edab3d2-311a-4782-9ec9-a70d0478b82f"></param>
+        /// <param name="stringParam" example="Example for StringProperty"></param>
+        /// <param name="badExampleIntParam" example="goodbye"></param>
+        public void ActionWithExampleParams(
+            bool boolParam,
+            int intParam,
+            long longParam,
+            float floatParam,
+            double doubleParam,
+            IntEnum enumParam,
+            Guid guidParam,
+            string stringParam,
+            int badExampleIntParam)
+        { }
     }
 }

test/Swashbuckle.AspNetCore.SwaggerGen.Test/XmlComments/XmlCommentsSchemaFilterTests.cs

@@ -4,7 +4,6 @@
 using System.IO;
 using Microsoft.OpenApi.Models;
 using Xunit;
-using Swashbuckle.AspNetCore.TestSupport;
 
 namespace Swashbuckle.AspNetCore.SwaggerGen.Test
 {
@@ -70,6 +69,42 @@ public void Apply_SetsDescription_FromActionParamTag()
             Assert.Equal("Description for param1", schema.Description);
         }
 
+        [Theory]
+        [InlineData(0, "boolean", null, true)]
+        [InlineData(1, "integer", "int32", 27)]
+        [InlineData(2, "integer", "int64", 4294967296L)]
+        [InlineData(3, "number", "float", 1.23F)]
+        [InlineData(4, "number", "double", 1.25D)]
+        [InlineData(5, "integer", "int32", 2)]
+        [InlineData(6, "string", "uuid", "1edab3d2-311a-4782-9ec9-a70d0478b82f")]
+        [InlineData(7, "string", null, "Example for StringProperty")]
+        [InlineData(8, "integer", "int32", null)]
+        public void Apply_SetsExample_FromActionParamTag(
+            int parameterIndex,
+            string schemaType,
+            string schemaFormat,
+            object expectedValue)
+        {
+            var schema = new OpenApiSchema { Type = schemaType, Format = schemaFormat };
+
+            var parameterInfo = typeof(FakeControllerWithXmlComments)
+                .GetMethod(nameof(FakeControllerWithXmlComments.ActionWithExampleParams))
+                .GetParameters()[parameterIndex];
+            var filterContext = new SchemaFilterContext(parameterInfo.ParameterType, null, null, parameterInfo: parameterInfo);
+
+            Subject().Apply(schema, filterContext);
+
+            if (expectedValue != null)
+            {
+                Assert.NotNull(schema.Example);
+                Assert.Equal(expectedValue, schema.Example.GetType().GetProperty("Value").GetValue(schema.Example));
+            }
+            else
+            {
+                Assert.Null(schema.Example);
+            }
+        }
+
         [Theory]
         [InlineData(typeof(XmlAnnotatedType), nameof(XmlAnnotatedType.BoolProperty), "boolean", null, true)]
         [InlineData(typeof(XmlAnnotatedType), nameof(XmlAnnotatedType.IntProperty), "integer", "int32", 10)]

test/WebSites/Basic/Controllers/CrudActionsController.cs

@@ -35,7 +35,7 @@ public Product Create([FromBody, Required]Product product)
         /// <summary>
         /// Searches the collection of products by description key words
         /// </summary>
-        /// <param name="keywords">A list of search terms</param>
+        /// <param name="keywords" example="hello">A list of search terms</param>
         /// <returns></returns>
         [HttpGet(Name = "SearchProducts")]
         public IEnumerable<Product> Get([FromQuery(Name = "kw")]string keywords = "foobar")
@@ -48,9 +48,9 @@ public IEnumerable<Product> Get([FromQuery(Name = "kw")]string keywords = "fooba
         }
 
         /// <summary>
-        /// Returns a specific product 
+        /// Returns a specific product
         /// </summary>
-        /// <param name="id"></param>
+        /// <param name="id" example="111">The product id</param>
         /// <returns></returns>
         [HttpGet("{id}", Name = "GetProduct")]
         public Product Get(int id)
@@ -61,7 +61,7 @@ public Product Get(int id)
         /// <summary>
         /// Updates all properties of a specific product
         /// </summary>
-        /// <param name="id"></param>
+        /// <param name="id" example="222"></param>
         /// <param name="product"></param>
         [HttpPut("{id}", Name = "UpdateProduct")]
         public void Update(int id, [FromBody, Required]Product product)
@@ -71,7 +71,7 @@ public void Update(int id, [FromBody, Required]Product product)
         /// <summary>
         /// Updates some properties of a specific product
         /// </summary>
-        /// <param name="id"></param>
+        /// <param name="id" example="333"></param>
         /// <param name="updates"></param>
         [HttpPatch("{id}", Name = "PatchProduct")]
         public void Patch(int id, [FromBody, Required]IDictionary<string, object> updates)
@@ -81,7 +81,7 @@ public void Patch(int id, [FromBody, Required]IDictionary<string, object> update
         /// <summary>
         /// Deletes a specific product
         /// </summary>
-        /// <param name="id"></param>
+        /// <param name="id" example="444"></param>
         [HttpDelete("{id}", Name = "DeleteProduct")]
         public void Delete(int id)
         {