Adding Api Explorer

Author: rynowak

Mvc.sln

@@ -1,7 +1,7 @@
 
 Microsoft Visual Studio Solution File, Format Version 12.00
 # Visual Studio 14
-VisualStudioVersion = 14.0.22115.0
+VisualStudioVersion = 14.0.22013.1
 MinimumVisualStudioVersion = 10.0.40219.1
 Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "samples", "samples", "{DAAE4C74-D06F-4874-A166-33305D2643CE}"
 EndProject
@@ -80,6 +80,8 @@ Project("{8BB2217D-0F2D-49D1-97BC-3654ED321F3B}") = "XmlSerializerWebSite", "tes
 EndProject
 Project("{8BB2217D-0F2D-49D1-97BC-3654ED321F3B}") = "UrlHelperWebSite", "test\WebSites\UrlHelperWebSite\UrlHelperWebSite.kproj", "{A192E504-2881-41DC-90D1-B7F1DD1134E8}"
 EndProject
+Project("{8BB2217D-0F2D-49D1-97BC-3654ED321F3B}") = "ApiExplorerWebSite", "test\WebSites\ApiExplorerWebSite\ApiExplorerWebSite.kproj", "{61061528-071E-424E-965A-07BCC2F02672}"
+EndProject
 Global
 	GlobalSection(SolutionConfigurationPlatforms) = preSolution
 		Debug|Any CPU = Debug|Any CPU
@@ -410,6 +412,16 @@ Global
 		{A192E504-2881-41DC-90D1-B7F1DD1134E8}.Release|Mixed Platforms.ActiveCfg = Release|Any CPU
 		{A192E504-2881-41DC-90D1-B7F1DD1134E8}.Release|Mixed Platforms.Build.0 = Release|Any CPU
 		{A192E504-2881-41DC-90D1-B7F1DD1134E8}.Release|x86.ActiveCfg = Release|Any CPU
+		{61061528-071E-424E-965A-07BCC2F02672}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{61061528-071E-424E-965A-07BCC2F02672}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{61061528-071E-424E-965A-07BCC2F02672}.Debug|Mixed Platforms.ActiveCfg = Debug|Any CPU
+		{61061528-071E-424E-965A-07BCC2F02672}.Debug|Mixed Platforms.Build.0 = Debug|Any CPU
+		{61061528-071E-424E-965A-07BCC2F02672}.Debug|x86.ActiveCfg = Debug|Any CPU
+		{61061528-071E-424E-965A-07BCC2F02672}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{61061528-071E-424E-965A-07BCC2F02672}.Release|Any CPU.Build.0 = Release|Any CPU
+		{61061528-071E-424E-965A-07BCC2F02672}.Release|Mixed Platforms.ActiveCfg = Release|Any CPU
+		{61061528-071E-424E-965A-07BCC2F02672}.Release|Mixed Platforms.Build.0 = Release|Any CPU
+		{61061528-071E-424E-965A-07BCC2F02672}.Release|x86.ActiveCfg = Release|Any CPU
 	EndGlobalSection
 	GlobalSection(SolutionProperties) = preSolution
 		HideSolutionNode = FALSE
@@ -448,5 +460,6 @@ Global
 		{1976AC4A-FEA4-4587-A158-D9F79736D2B6} = {16703B76-C9F7-4C75-AE6C-53D92E308E3C}
 		{96107AC0-18E2-474D-BAB4-2FFF2185FBCD} = {16703B76-C9F7-4C75-AE6C-53D92E308E3C}
 		{A192E504-2881-41DC-90D1-B7F1DD1134E8} = {16703B76-C9F7-4C75-AE6C-53D92E308E3C}
+		{61061528-071E-424E-965A-07BCC2F02672} = {16703B76-C9F7-4C75-AE6C-53D92E308E3C}
 	EndGlobalSection
 EndGlobal

samples/MvcSample.Web/ApiExplorerController.cs

@@ -0,0 +1,22 @@
+// Copyright (c) Microsoft Open Technologies, Inc. All rights reserved.
+// Licensed under the Apache License, Version 2.0. See License.txt in the project root for license information.
+
+using Microsoft.AspNet.Mvc;
+using Microsoft.AspNet.Mvc.Description;
+
+namespace MvcSample.Web
+{
+    [Route("ApiExplorer")]
+    public class ApiExplorerController : Controller
+    {
+        [Activate]
+        public IApiDescriptionGroupCollectionProvider Provider { get; set; }
+
+        [HttpGet]
+        public IActionResult All()
+        {
+            var descriptions = Provider.ApiDescriptionGroups.Items;
+            return View(descriptions);
+        }
+    }
+}

samples/MvcSample.Web/Content/api-description.css

@@ -0,0 +1,10 @@
+.api-description {
+    margin: 10px 0px 10px 0px;
+    padding: 5px;
+}
+
+.api-description hr {
+    border: 0px;
+    border-top: 1px solid #D44B4B;
+    margin: 0px;
+}

samples/MvcSample.Web/Controllers/ApiExplorerSamples/ProductsAdminController.cs

@@ -0,0 +1,38 @@
+using Microsoft.AspNet.Mvc;
+using System;
+using System.Collections.Generic;
+
+namespace MvcSample.Web.ApiExplorerSamples
+{
+    [ApiExplorerSettings(GroupName = "Admin API")]
+    [Route("api/Admin/Products")]
+    public class ProductsAdminController : Controller
+    {
+        [HttpPut]
+        public void AddProduct([FromBody] Product product)
+        {
+        }
+
+        [HttpPost("{id}")]
+        public void UpdateProduct([FromBody] Product product)
+        {
+        }
+
+        [HttpPost("{id}/Stock")]
+        public void SetQuantityInStock(int id, int quantity)
+        {
+        }
+
+        [HttpPost("{id}/Price")]
+        public void SetPrice(int id, decimal price)
+        {
+        }
+
+        [Produces("application/json", "application/xml")]
+        [HttpGet("{id}/Orders")]
+        public IEnumerable<ProductOrderConfirmation> GetOrders(DateTime? fromData = null, DateTime? toDate = null)
+        {
+            return null;
+        }
+    }
+}

samples/MvcSample.Web/Controllers/ApiExplorerSamples/ProductsController.cs

@@ -0,0 +1,31 @@
+using System;
+using Microsoft.AspNet.Mvc;
+using System.Collections.Generic;
+
+namespace MvcSample.Web.ApiExplorerSamples
+{
+    [ApiExplorerSettings(GroupName = "Public API")]
+    [Produces("application/json")]
+    [Route("api/Products")]
+    public class ProductsController : Controller
+    {
+        [HttpGet("{id}")]
+        public Product GetById(int id)
+        {
+            return null;
+        }
+
+        [HttpGet("Search/{name}")]
+        public IEnumerable<Product> SearchByName(string name)
+        {
+            return null;
+        }
+
+        [Produces("application/json", Type = typeof(ProductOrderConfirmation))]
+        [HttpPut("{id}/Buy")]
+        public IActionResult Buy(int projectId, int quantity = 1)
+        {
+            return null;
+        }
+    }
+}

samples/MvcSample.Web/Models/ApiExplorerSamples/Product.cs

@@ -0,0 +1,13 @@
+using System;
+
+namespace MvcSample.Web.ApiExplorerSamples
+{
+    public class Product
+    {
+        public string Name { get; set; }
+
+        public string Description { get; set; }
+
+        public decimal Price { get; set; }
+    }
+}

samples/MvcSample.Web/Models/ApiExplorerSamples/ProductOrderConfirmation.cs

@@ -0,0 +1,15 @@
+using System;
+
+namespace MvcSample.Web.ApiExplorerSamples
+{
+    public class ProductOrderConfirmation
+    {
+        public Product Product { get; set; }
+
+        public decimal PricePerUnit { get; set; }
+
+        public int Quantity { get; set; }
+
+        public decimal TotalPrice { get; set; }
+    }
+}

samples/MvcSample.Web/Views/ApiExplorer/All.cshtml

@@ -0,0 +1,23 @@
+@using Microsoft.AspNet.Mvc.Description
+@model IReadOnlyList<ApiDescriptionGroup>
+
+@section header
+{
+    <link rel="stylesheet" href="~/Content/api-description.css" />
+}
+
+<div style="padding: 50px 0px 0px 0px">
+
+    @foreach (var group in Model)
+    {
+        <div class="row">
+            <h1>Group: @group.GroupName</h1>
+
+            @foreach (var item in group.Items)
+            {
+                await Html.RenderPartialAsync("_ApiDescription", item);
+            }
+            
+        </div>
+    }
+</div>

samples/MvcSample.Web/Views/ApiExplorer/_ApiDescription.cshtml

@@ -0,0 +1,31 @@
+@using Microsoft.AspNet.Mvc.Description
+@model ApiDescription
+
+<div class="api-description">
+    <h4>@(Model.HttpMethod ?? "*") - @(Model.RelativePath ?? "Unknown Url")</h4>
+    <hr />
+    <h5>For action: @Model.ActionDescriptor.DisplayName</h5>
+    <p>Return Type: @(Model.ResponseType?.FullName ?? "Unknown Type")</p>
+
+    @if (Model.ParameterDescriptions.Count > 0)
+    {
+        <p>Parameters:</p>
+        <ul>
+            @foreach (var parameter in Model.ParameterDescriptions)
+            {
+                <li>@parameter.Name - @parameter.Type.FullName - @parameter.Source.ToString()</li>
+            }
+        </ul>
+    }
+
+    @if (Model.SupportedResponseFormats.Count > 0)
+    {
+        <p>Response Formats:</p>
+        <ul>
+            @foreach(var response in Model.SupportedResponseFormats)
+            {
+                <li>@response.MediaType.RawValue - @response.Formatter.GetType().Name</li>
+            }
+        </ul>
+    }
+</div>

src/Microsoft.AspNet.Mvc.Core/ActionDescriptor.cs

@@ -11,6 +11,7 @@ public class ActionDescriptor
     {
         public ActionDescriptor()
         {
+            Properties = new Dictionary<object, object>();
             RouteValueDefaults = new Dictionary<string, object>(StringComparer.OrdinalIgnoreCase);
         }
 
@@ -34,5 +35,10 @@ public ActionDescriptor()
         /// A friendly name for this action.
         /// </summary>
         public virtual string DisplayName { get; set; }
+
+        /// <summary>
+        /// Stores arbitrary metadata properties associated with the <see cref="ActionDescriptor"/>.
+        /// </summary>
+        public IDictionary<object, object> Properties { get; private set; }
     }
 }

src/Microsoft.AspNet.Mvc.Core/ActionDescriptorExtensions.cs

@@ -0,0 +1,43 @@
+// Copyright (c) Microsoft Open Technologies, Inc. All rights reserved.
+// Licensed under the Apache License, Version 2.0. See License.txt in the project root for license information.
+
+namespace Microsoft.AspNet.Mvc
+{
+    /// <summary>
+    /// Extension methods for <see cref="ActionDescriptor"/>.
+    /// </summary>
+    public static class ActionDescriptorExtensions
+    {
+        /// <summary>
+        /// Gets the value of a property from the <see cref="ActionDescriptor.Properties"/> collection 
+        /// using the provided value of <typeparamref name="T"/> as the key.
+        /// </summary>
+        /// <typeparam name="T">The type of the property.</typeparam>
+        /// <param name="actionDescriptor">The action descriptor.</param>
+        /// <returns>The property or the default value of <typeparamref name="T"/>.</returns>
+        public static T GetProperty<T>([NotNull] this ActionDescriptor actionDescriptor)
+        {
+            object value;
+            if (actionDescriptor.Properties.TryGetValue(typeof(T), out value))
+            {
+                return (T)value;
+            }
+            else
+            {
+                return default(T);
+            }
+        }
+
+        /// <summary>
+        /// Sets the value of an property in the <see cref="ActionDescriptor.Properties"/> collection using
+        /// the provided value of <typeparamref name="T"/> as the key.
+        /// </summary>
+        /// <typeparam name="T">The type of the property.</typeparam>
+        /// <param name="actionDescriptor">The action descriptor.</param>
+        /// <param name="value">The value of the property.</param>
+        public static void SetProperty<T>([NotNull] this ActionDescriptor actionDescriptor, [NotNull] T value)
+        {
+            actionDescriptor.Properties[typeof(T)] = value;
+        }
+    }
+}

src/Microsoft.AspNet.Mvc.Core/Description/ApiDescription.cs

@@ -0,0 +1,81 @@
+// Copyright (c) Microsoft Open Technologies, Inc. All rights reserved.
+// Licensed under the Apache License, Version 2.0. See License.txt in the project root for license information.
+
+using System;
+using System.Collections.Generic;
+using Microsoft.AspNet.Mvc.ModelBinding;
+
+namespace Microsoft.AspNet.Mvc.Description
+{
+    /// <summary>
+    /// Represents an API exposed by this application.
+    /// </summary>
+    public class ApiDescription
+    {
+        /// <summary>
+        /// Creates a new instance of <see cref="ApiDescription"/>.
+        /// </summary>
+        public ApiDescription()
+        {
+            Properties = new Dictionary<object, object>();
+            ParameterDescriptions = new List<ApiParameterDescription>();
+            SupportedResponseFormats = new List<ApiResponseFormat>();
+        }
+
+        /// <summary>
+        /// The <see cref="ActionDescriptor"/> for this api.
+        /// </summary>
+        public ActionDescriptor ActionDescriptor { get; set; }
+
+        /// <summary>
+        /// The group name for this api.
+        /// </summary>
+        public string GroupName { get; set; }
+
+        /// <summary>
+        /// The supported HTTP method for this api, or null if all HTTP methods are supported.
+        /// </summary>
+        public string HttpMethod { get; set; }
+
+        /// <summary>
+        /// The list of <see cref="ApiParameterDescription"/> for this api.
+        /// </summary>
+        public List<ApiParameterDescription> ParameterDescriptions { get; private set; }
+
+        /// <summary>
+        /// Stores arbitrary metadata properties associated with the <see cref="ApiDescription"/>.
+        /// </summary>
+        public IDictionary<object, object> Properties { get; private set; }
+
+        /// <summary>
+        /// The relative url path template (relative to application root) for this api.
+        /// </summary>
+        public string RelativePath { get; set; }
+
+        /// <summary>
+        /// The <see cref="ModelMetadata"/> for the <see cref="ResponseType"/> or null.
+        /// </summary>
+        /// <remarks>
+        /// Will be null if <see cref="ResponseType"/> is null.
+        /// </remarks>
+        public ModelMetadata ResponseModelMetadata { get; set; }
+
+        /// <summary>
+        /// The CLR data type of the response or null.
+        /// </summary>
+        /// <remarks>
+        /// Will be null if the action returns no response, or if the response type is unclear. Use 
+        /// <see cref="ProducesAttribute"/> on an action method to specify a response type.
+        /// </remarks>
+        public Type ResponseType { get; set; }
+
+        /// <summary>
+        /// A list of possible formats for a response.
+        /// </summary>
+        /// <remarks>
+        /// Will be empty if the action returns no response, or if the response type is unclear. Use
+        /// <see cref="ProducesAttribute"/> on an action method to specify a response type.
+        /// </remarks>
+        public IList<ApiResponseFormat> SupportedResponseFormats { get; private set; }
+    }
+}