Example for request/response payload (#95)

Author: justinyoo

samples/Microsoft.Azure.WebJobs.Extensions.OpenApi.FunctionApp.Models/Category.cs

@@ -1,8 +1,12 @@
+using Microsoft.Azure.WebJobs.Extensions.OpenApi.Core.Attributes;
+using Microsoft.Azure.WebJobs.Extensions.OpenApi.FunctionApp.Models.Examples;
+
 namespace Microsoft.Azure.WebJobs.Extensions.OpenApi.FunctionApp.Models
 {
     /// <summary>
     /// This represents the model entity for category of Swagger Pet Store.
     /// </summary>
+    [OpenApiExample(typeof(CategoryExample))]
     public class Category
     {
         /// <summary>

samples/Microsoft.Azure.WebJobs.Extensions.OpenApi.FunctionApp.Models/DummyStringModel.cs

@@ -1,7 +1,11 @@
 using System;
 
+using Microsoft.Azure.WebJobs.Extensions.OpenApi.Core.Attributes;
+using Microsoft.Azure.WebJobs.Extensions.OpenApi.FunctionApp.Models.Examples;
+
 namespace Microsoft.Azure.WebJobs.Extensions.OpenApi.FunctionApp.Models
 {
+    [OpenApiExample(typeof(DummyStringModelExample))]
     public class DummyStringModel
     {
         public string StringValue { get; set; }

samples/Microsoft.Azure.WebJobs.Extensions.OpenApi.FunctionApp.Models/Examples/CategoryExample.cs

@@ -0,0 +1,17 @@
+using Microsoft.Azure.WebJobs.Extensions.OpenApi.Core.Abstractions;
+using Microsoft.Azure.WebJobs.Extensions.OpenApi.Core.Resolvers;
+
+using Newtonsoft.Json.Serialization;
+
+namespace Microsoft.Azure.WebJobs.Extensions.OpenApi.FunctionApp.Models.Examples
+{
+    public class CategoryExample : OpenApiExample<Category>
+    {
+        public override IOpenApiExample<Category> Build(NamingStrategy namingStrategy = null)
+        {
+            this.Examples.Add(OpenApiExampleResolver.Resolve("first", new Category() { Id = (long)123, Name = "Hello World" }, namingStrategy));
+
+            return this;
+        }
+    }
+}

samples/Microsoft.Azure.WebJobs.Extensions.OpenApi.FunctionApp.Models/Examples/DummyStringModelExample.cs

@@ -0,0 +1,20 @@
+using System;
+
+using Microsoft.Azure.WebJobs.Extensions.OpenApi.Core.Abstractions;
+using Microsoft.Azure.WebJobs.Extensions.OpenApi.Core.Resolvers;
+
+using Newtonsoft.Json.Serialization;
+
+namespace Microsoft.Azure.WebJobs.Extensions.OpenApi.FunctionApp.Models.Examples
+{
+    public class DummyStringModelExample : OpenApiExample<DummyStringModel>
+    {
+        public override IOpenApiExample<DummyStringModel> Build(NamingStrategy namingStrategy = null)
+        {
+            this.Examples.Add(OpenApiExampleResolver.Resolve("lorem", new DummyStringModel() { StringValue = "Hello World", UriValue = new Uri("http://localhost:80") }, namingStrategy));
+            this.Examples.Add(OpenApiExampleResolver.Resolve("ipsum", new DummyStringModel() { StringValue = "Hello World 2", UriValue = new Uri("https://localhost:443") }, namingStrategy));
+
+            return this;
+        }
+    }
+}

samples/Microsoft.Azure.WebJobs.Extensions.OpenApi.FunctionApp.V3Static/DummyHttpTrigger.cs

@@ -8,6 +8,8 @@
 using Microsoft.Azure.WebJobs.Extensions.OpenApi.Core.Attributes;
 using Microsoft.Azure.WebJobs.Extensions.OpenApi.Core.Enums;
 using Microsoft.Azure.WebJobs.Extensions.OpenApi.FunctionApp.Models;
+using Microsoft.Azure.WebJobs.Extensions.OpenApi.FunctionApp.Models.Examples;
+using Microsoft.Azure.WebJobs.Extensions.OpenApi.FunctionApp.V3Static.Examples;
 using Microsoft.Azure.WebJobs.Extensions.OpenApi.FunctionApp.V3Static.ResponseHeaders;
 using Microsoft.Extensions.Logging;
 using Microsoft.OpenApi.Models;
@@ -58,9 +60,10 @@ public static async Task<IActionResult> AddDummy(
         [FunctionName(nameof(DummyHttpTrigger.UpdateDummies))]
         [OpenApiOperation(operationId: "updateDummies", tags: new[] { "dummy" }, Summary = "Updates a list of dummies", Description = "This updates a list of dummies.", Visibility = OpenApiVisibilityType.Advanced)]
         [OpenApiSecurity("function_key", SecuritySchemeType.ApiKey, Name = "code", In = OpenApiSecurityLocationType.Query)]
-        [OpenApiRequestBody(contentType: "application/json", bodyType: typeof(DummyListModel), Required = true, Description = "Dummy list model")]
+        [OpenApiRequestBody(contentType: "application/json", bodyType: typeof(DummyListModel), Example = typeof(DummyListModelExample), Required = true, Description = "Dummy list model")]
+        [OpenApiResponseWithBody(statusCode: HttpStatusCode.OK, contentType: "application/json", bodyType: typeof(DummyArrayResponseModel), Summary = "Dummy response", Description = "This returns the dummy response", Deprecated = true, CustomHeaderType = typeof(DummyResponseHeader))]
         [OpenApiResponseWithBody(statusCode: HttpStatusCode.OK, contentType: "application/json", bodyType: typeof(List<DummyStringModel>), Summary = "Dummy response", Description = "This returns the dummy response", CustomHeaderType = typeof(DummyResponseHeader))]
-        [OpenApiResponseWithBody(statusCode: HttpStatusCode.OK, contentType: "application/json", bodyType: typeof(DummyStringModel), Summary = "Dummy response", Description = "This returns the dummy response", Deprecated = true, CustomHeaderType = typeof(DummyResponseHeader))]
+        [OpenApiResponseWithBody(statusCode: HttpStatusCode.Created, contentType: "application/json", bodyType: typeof(DummyStringModel), Example = typeof(DummyStringModelExample), Summary = "Dummy response", Description = "This returns the dummy response", CustomHeaderType = typeof(DummyResponseHeader))]
         public static async Task<IActionResult> UpdateDummies(
             [HttpTrigger(AuthorizationLevel.Function, "PUT", Route = "dummies")] HttpRequest req,
             ILogger log)

samples/Microsoft.Azure.WebJobs.Extensions.OpenApi.FunctionApp.V3Static/Examples/DummyListModelExample.cs

@@ -0,0 +1,29 @@
+using System;
+using System.Collections.Generic;
+
+using Microsoft.Azure.WebJobs.Extensions.OpenApi.Core.Abstractions;
+using Microsoft.Azure.WebJobs.Extensions.OpenApi.Core.Resolvers;
+using Microsoft.Azure.WebJobs.Extensions.OpenApi.FunctionApp.Models;
+
+using Newtonsoft.Json.Serialization;
+
+namespace Microsoft.Azure.WebJobs.Extensions.OpenApi.FunctionApp.V3Static.Examples
+{
+    public class DummyListModelExample : OpenApiExample<DummyListModel>
+    {
+        public override IOpenApiExample<DummyListModel> Build(NamingStrategy namingStrategy = null)
+        {
+            this.Examples.Add(
+                OpenApiExampleResolver.Resolve(
+                    "dummy",
+                    new DummyListModel()
+                    {
+                        ListValues = new List<DummyStringModel>() { new DummyStringModel() { StringValue = "Hello World", UriValue = new Uri("https://localhost") } }
+                    },
+                    namingStrategy
+                ));
+
+            return this;
+        }
+    }
+}

src/Microsoft.Azure.WebJobs.Extensions.OpenApi.Core/Abstractions/IOpenApiExample.cs

@@ -0,0 +1,27 @@
+using System.Collections.Generic;
+
+using Microsoft.OpenApi.Models;
+
+using Newtonsoft.Json.Serialization;
+
+namespace Microsoft.Azure.WebJobs.Extensions.OpenApi.Core.Abstractions
+{
+    /// <summary>
+    /// This provides interfaces to classes to render example data.
+    /// </summary>
+    /// <typeparam name="T">Type of the example object.</typeparam>
+    public interface IOpenApiExample<T>
+    {
+        /// <summary>
+        /// Gets the collection of the <see cref="OpenApiExample"/> objects.
+        /// </summary>
+        IDictionary<string, OpenApiExample> Examples { get; }
+
+        /// <summary>
+        /// Builds the example.
+        /// </summary>
+        /// <param name="namingStrategy"><see cref="NamingStrategy"/> instance.</param>
+        /// <returns>Returns <see cref="IOpenApiExample{T}"/> instance.</returns>
+        IOpenApiExample<T> Build(NamingStrategy namingStrategy = null);
+    }
+}

src/Microsoft.Azure.WebJobs.Extensions.OpenApi.Core/Abstractions/OpenApiExample.cs

@@ -0,0 +1,21 @@
+using System.Collections.Generic;
+
+using Microsoft.OpenApi.Models;
+
+using Newtonsoft.Json.Serialization;
+
+namespace Microsoft.Azure.WebJobs.Extensions.OpenApi.Core.Abstractions
+{
+    /// <summary>
+    /// This represents the example entity for models. This MUST be inherited.
+    /// </summary>
+    /// <typeparam name="T">Type of model as an example.</typeparam>
+    public abstract class OpenApiExample<T> : IOpenApiExample<T>
+    {
+        /// <inheritdoc />
+        public IDictionary<string, OpenApiExample> Examples { get; } = new Dictionary<string, OpenApiExample>();
+
+        /// <inheritdoc />
+        public abstract IOpenApiExample<T> Build(NamingStrategy namingStrategy = null);
+    }
+}

src/Microsoft.Azure.WebJobs.Extensions.OpenApi.Core/Attributes/OpenApiExampleAttribute.cs

@@ -0,0 +1,27 @@
+using System;
+
+using Microsoft.Azure.WebJobs.Extensions.OpenApi.Core.Abstractions;
+using Microsoft.Azure.WebJobs.Extensions.OpenApi.Core.Extensions;
+
+namespace Microsoft.Azure.WebJobs.Extensions.OpenApi.Core.Attributes
+{
+    /// <summary>
+    /// This represents the attribute entity for the example.
+    /// </summary>
+    [AttributeUsage(AttributeTargets.Class, AllowMultiple = false, Inherited = false)]
+    public class OpenApiExampleAttribute : Attribute
+    {
+        /// <summary>
+        /// Initializes a new instance of the <see cref="OpenApiExampleAttribute"/> class.
+        /// </summary>
+        public OpenApiExampleAttribute(Type example)
+        {
+            this.Example = example.ThrowIfNullOrDefault();
+        }
+
+        /// <summary>
+        /// Gets the type of the example. It SHOULD be inheriting the <see cref="OpenApiExample{T}"/> class.
+        /// </summary>
+        public virtual Type Example { get; }
+    }
+}

src/Microsoft.Azure.WebJobs.Extensions.OpenApi.Core/Attributes/OpenApiPayloadAttribute.cs

@@ -1,5 +1,7 @@
 using System;
 
+using Microsoft.Azure.WebJobs.Extensions.OpenApi.Core.Abstractions;
+
 namespace Microsoft.Azure.WebJobs.Extensions.OpenApi.Core.Attributes
 {
     /// <summary>
@@ -32,5 +34,10 @@ protected OpenApiPayloadAttribute(string contentType, Type bodyType)
         /// Gets or sets the description.
         /// </summary>
         public virtual string Description { get; set; }
+
+        /// <summary>
+        /// Gets or sets the type of the example. It SHOULD be inheriting the <see cref="OpenApiExample{T}"/> class.
+        /// </summary>
+        public virtual Type Example { get; set; }
     }
 }