Added initial support for OData API explorer

Author: Chris Martinez

ApiVersioning.sln

@@ -1,7 +1,7 @@
 
 Microsoft Visual Studio Solution File, Format Version 12.00
 # Visual Studio 15
-VisualStudioVersion = 15.0.26228.9
+VisualStudioVersion = 15.0.26403.3
 MinimumVisualStudioVersion = 10.0.40219.1
 Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "src", "src", "{4D5F5F21-0CB7-4B4E-A42F-732BD4AFD0FF}"
 EndProject
@@ -54,6 +54,10 @@ Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "Microsoft.AspNetCore.Mvc.Ve
 EndProject
 Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "Microsoft.AspNetCore.Mvc.Versioning.ApiExplorer.Tests", "test\Microsoft.AspNetCore.Mvc.Versioning.ApiExplorer.Tests\Microsoft.AspNetCore.Mvc.Versioning.ApiExplorer.Tests.csproj", "{C8D29CB1-C541-4579-A1B8-AFD4B4F5F4A3}"
 EndProject
+Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "Microsoft.AspNet.OData.Versioning.ApiExplorer", "src\Microsoft.AspNet.OData.Versioning.ApiExplorer\Microsoft.AspNet.OData.Versioning.ApiExplorer.csproj", "{6ED07FE1-95D3-41E9-A0F1-AEF1BBD6A474}"
+EndProject
+Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "Microsoft.AspNet.OData.Versioning.ApiExplorer.Tests", "test\Microsoft.AspNet.OData.Versioning.ApiExplorer.Tests\Microsoft.AspNet.OData.Versioning.ApiExplorer.Tests.csproj", "{280C3B03-5EED-40E9-A826-83C9F3C6EEDC}"
+EndProject
 Global
 	GlobalSection(SharedMSBuildProjectFiles) = preSolution
 		test\Acceptance.Test.Shared\Acceptance.Test.Shared.projitems*{6cdfb878-2642-4f98-ae35-621bac581181}*SharedItemsImports = 13
@@ -114,6 +118,14 @@ Global
 		{C8D29CB1-C541-4579-A1B8-AFD4B4F5F4A3}.Debug|Any CPU.Build.0 = Debug|Any CPU
 		{C8D29CB1-C541-4579-A1B8-AFD4B4F5F4A3}.Release|Any CPU.ActiveCfg = Release|Any CPU
 		{C8D29CB1-C541-4579-A1B8-AFD4B4F5F4A3}.Release|Any CPU.Build.0 = Release|Any CPU
+		{6ED07FE1-95D3-41E9-A0F1-AEF1BBD6A474}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{6ED07FE1-95D3-41E9-A0F1-AEF1BBD6A474}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{6ED07FE1-95D3-41E9-A0F1-AEF1BBD6A474}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{6ED07FE1-95D3-41E9-A0F1-AEF1BBD6A474}.Release|Any CPU.Build.0 = Release|Any CPU
+		{280C3B03-5EED-40E9-A826-83C9F3C6EEDC}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{280C3B03-5EED-40E9-A826-83C9F3C6EEDC}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{280C3B03-5EED-40E9-A826-83C9F3C6EEDC}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{280C3B03-5EED-40E9-A826-83C9F3C6EEDC}.Release|Any CPU.Build.0 = Release|Any CPU
 	EndGlobalSection
 	GlobalSection(SolutionProperties) = preSolution
 		HideSolutionNode = FALSE
@@ -135,5 +147,7 @@ Global
 		{AAFE5030-DF0A-4156-9AF5-1AAA53CA1FF9} = {0987757E-4D09-4523-B9C9-65B1E8832AA1}
 		{FE19225D-6564-4FCF-BA1C-0ED5CA336C44} = {4D5F5F21-0CB7-4B4E-A42F-732BD4AFD0FF}
 		{C8D29CB1-C541-4579-A1B8-AFD4B4F5F4A3} = {0987757E-4D09-4523-B9C9-65B1E8832AA1}
+		{6ED07FE1-95D3-41E9-A0F1-AEF1BBD6A474} = {4D5F5F21-0CB7-4B4E-A42F-732BD4AFD0FF}
+		{280C3B03-5EED-40E9-A826-83C9F3C6EEDC} = {0987757E-4D09-4523-B9C9-65B1E8832AA1}
 	EndGlobalSection
 EndGlobal

ApiVersioningWithSamples.sln

@@ -1,7 +1,7 @@
 
 Microsoft Visual Studio Solution File, Format Version 12.00
 # Visual Studio 15
-VisualStudioVersion = 15.0.26228.10
+VisualStudioVersion = 15.0.26403.3
 MinimumVisualStudioVersion = 10.0.40219.1
 Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "src", "src", "{4D5F5F21-0CB7-4B4E-A42F-732BD4AFD0FF}"
 EndProject
@@ -88,6 +88,12 @@ Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "SwaggerSample", "samples\as
 EndProject
 Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "SwaggerWebApiSample", "samples\webapi\SwaggerWebApiSample\SwaggerWebApiSample.csproj", "{6BEDE228-4BE9-499E-B1E6-93B6B0AC62DA}"
 EndProject
+Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "SwaggerODataWebApiSample", "samples\webapi\SwaggerODataWebApiSample\SwaggerODataWebApiSample.csproj", "{F3986F7B-AF76-43D1-A44F-303023A08CD3}"
+EndProject
+Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "Microsoft.AspNet.OData.Versioning.ApiExplorer", "src\Microsoft.AspNet.OData.Versioning.ApiExplorer\Microsoft.AspNet.OData.Versioning.ApiExplorer.csproj", "{1B255310-A2B7-437F-804F-6E1D8C940A17}"
+EndProject
+Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "Microsoft.AspNet.OData.Versioning.ApiExplorer.Tests", "test\Microsoft.AspNet.OData.Versioning.ApiExplorer.Tests\Microsoft.AspNet.OData.Versioning.ApiExplorer.Tests.csproj", "{3B7E0FEF-8019-4A17-A55F-A6FA378DA856}"
+EndProject
 Global
 	GlobalSection(SharedMSBuildProjectFiles) = preSolution
 		test\Acceptance.Test.Shared\Acceptance.Test.Shared.projitems*{6cdfb878-2642-4f98-ae35-621bac581181}*SharedItemsImports = 13
@@ -192,6 +198,18 @@ Global
 		{6BEDE228-4BE9-499E-B1E6-93B6B0AC62DA}.Debug|Any CPU.Build.0 = Debug|Any CPU
 		{6BEDE228-4BE9-499E-B1E6-93B6B0AC62DA}.Release|Any CPU.ActiveCfg = Release|Any CPU
 		{6BEDE228-4BE9-499E-B1E6-93B6B0AC62DA}.Release|Any CPU.Build.0 = Release|Any CPU
+		{F3986F7B-AF76-43D1-A44F-303023A08CD3}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{F3986F7B-AF76-43D1-A44F-303023A08CD3}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{F3986F7B-AF76-43D1-A44F-303023A08CD3}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{F3986F7B-AF76-43D1-A44F-303023A08CD3}.Release|Any CPU.Build.0 = Release|Any CPU
+		{1B255310-A2B7-437F-804F-6E1D8C940A17}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{1B255310-A2B7-437F-804F-6E1D8C940A17}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{1B255310-A2B7-437F-804F-6E1D8C940A17}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{1B255310-A2B7-437F-804F-6E1D8C940A17}.Release|Any CPU.Build.0 = Release|Any CPU
+		{3B7E0FEF-8019-4A17-A55F-A6FA378DA856}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{3B7E0FEF-8019-4A17-A55F-A6FA378DA856}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{3B7E0FEF-8019-4A17-A55F-A6FA378DA856}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{3B7E0FEF-8019-4A17-A55F-A6FA378DA856}.Release|Any CPU.Build.0 = Release|Any CPU
 	EndGlobalSection
 	GlobalSection(SolutionProperties) = preSolution
 		HideSolutionNode = FALSE
@@ -226,5 +244,8 @@ Global
 		{15461DBB-95AD-4CA7-AF41-E70F54860FE3} = {0987757E-4D09-4523-B9C9-65B1E8832AA1}
 		{D95BC932-50F7-4014-970E-0C6E8400BE25} = {900DD210-8500-4D89-A05D-C9526935A719}
 		{6BEDE228-4BE9-499E-B1E6-93B6B0AC62DA} = {F446ED94-368F-4F67-913B-16E82CA80DFC}
+		{F3986F7B-AF76-43D1-A44F-303023A08CD3} = {F446ED94-368F-4F67-913B-16E82CA80DFC}
+		{1B255310-A2B7-437F-804F-6E1D8C940A17} = {4D5F5F21-0CB7-4B4E-A42F-732BD4AFD0FF}
+		{3B7E0FEF-8019-4A17-A55F-A6FA378DA856} = {0987757E-4D09-4523-B9C9-65B1E8832AA1}
 	EndGlobalSection
 EndGlobal

samples/webapi/SwaggerODataWebApiSample/CaseInsensitiveODataUriResolver.cs

@@ -0,0 +1,23 @@
+namespace Microsoft.Examples
+{
+    using Microsoft.OData.UriParser;
+    using System;
+
+    /// <summary>
+    /// Represents a case-insensitive URI resolver.
+    /// </summary>
+    /// <remarks>
+    /// <list type="bullet">
+    ///  <item>HACK: required due to bug in ODL</item>
+    ///  <item>REF: https://github.com/OData/odata.net/issues/695</item>
+    /// </list></remarks>
+    public sealed class CaseInsensitiveODataUriResolver : UnqualifiedODataUriResolver
+    {
+        /// <summary>
+        /// Gets or sets whether the URI resolver is case-sensitive.
+        /// </summary>
+        /// <value>True if the URI resolver is case-sensitive; otherwise, false.</value>
+        /// <remarks>This property will always return <c>false</c>.</remarks>
+        public override bool EnableCaseInsensitive { get { return true; } set { } }
+    }
+}

samples/webapi/SwaggerODataWebApiSample/Configuration/OrderModelConfiguration.cs

@@ -0,0 +1,30 @@
+namespace Microsoft.Examples.Configuration
+{
+    using Microsoft.Web.Http;
+    using Microsoft.Web.OData.Builder;
+    using Models;
+    using System.Web.OData.Builder;
+
+    /// <summary>
+    /// Represents the model configuration for <see cref="Order">orders</see>.
+    /// </summary>
+    public class OrderModelConfiguration : IModelConfiguration
+    {
+        /// <summary>
+        /// Applies model configurations using the provided builder for the specified API version.
+        /// </summary>
+        /// <param name="builder">The <see cref="ODataModelBuilder">builder</see> used to apply configurations.</param>
+        /// <param name="apiVersion">The <see cref="ApiVersion">API version</see> associated with the <paramref name="builder"/>.</param>
+        public void Apply( ODataModelBuilder builder, ApiVersion apiVersion )
+        {
+            var order = builder.EntitySet<Order>( "Orders" ).EntityType;
+
+            order.HasKey( o => o.Id );
+
+            if ( apiVersion < ApiVersions.V2 )
+            {
+                order.Ignore( o => o.EffectiveDate );
+            }
+        }
+    }
+}

samples/webapi/SwaggerODataWebApiSample/Configuration/PersonModelConfiguration.cs

@@ -0,0 +1,35 @@
+namespace Microsoft.Examples.Configuration
+{
+    using Microsoft.Web.Http;
+    using Microsoft.Web.OData.Builder;
+    using Models;
+    using System.Web.OData.Builder;
+
+    /// <summary>
+    /// Represents the model configuration for <see cref="Person">people</see>.
+    /// </summary>
+    public class PersonModelConfiguration : IModelConfiguration
+    {
+        /// <summary>
+        /// Applies model configurations using the provided builder for the specified API version.
+        /// </summary>
+        /// <param name="builder">The <see cref="ODataModelBuilder">builder</see> used to apply configurations.</param>
+        /// <param name="apiVersion">The <see cref="ApiVersion">API version</see> associated with the <paramref name="builder"/>.</param>
+        public void Apply( ODataModelBuilder builder, ApiVersion apiVersion )
+        {
+            var person = builder.EntitySet<Person>( "People" ).EntityType;
+
+            person.HasKey( p => p.Id );
+
+            if ( apiVersion < ApiVersions.V3 )
+            {
+                person.Ignore( p => p.Phone );
+            }
+
+            if ( apiVersion < ApiVersions.V2 )
+            {
+                person.Ignore( p => p.Email );
+            }
+        }
+    }
+}

samples/webapi/SwaggerODataWebApiSample/ImplicitApiVersionParameter.cs

@@ -0,0 +1,71 @@
+namespace Microsoft.Examples
+{
+    using Microsoft.Web.Http.Description;
+    using Swashbuckle.Swagger;
+    using System.Collections.Generic;
+    using System.Linq;
+    using System.Web.Http.Description;
+
+    /// <summary>
+    /// Represents the Swagger/Swashbuckle operation filter used to document the implicit API version parameter.
+    /// </summary>
+    public class ImplicitApiVersionParameter : IOperationFilter
+    {
+        /// <summary>
+        /// Applies the filter to the specified operation using the given context.
+        /// </summary>
+        /// <param name="operation">The operation to apply the filter to.</param>
+        /// <param name="schemaRegistry">The API schema registry.</param>
+        /// <param name="apiDescription">The API description being filtered.</param>
+        public void Apply( Operation operation, SchemaRegistry schemaRegistry, ApiDescription apiDescription )
+        {
+            var description = apiDescription as VersionedApiDescription;
+
+            // if the api explorer did not capture an API version for this operation
+            // then the action must be API version-neutral; there's nothing to add
+            if ( description?.ApiVersion == null )
+            {
+                return;
+            }
+
+            var parameters = operation.parameters;
+
+            if ( parameters == null )
+            {
+                operation.parameters = parameters = new List<Parameter>();
+            }
+
+            // note: in most applications, service authors will choose a single, consistent
+            // approach to how API versioning is applied. this sample uses a:
+            //
+            // 1. query string parameter method with the name "api-version"
+            // 2. url path segement with the route parameter name "api-version"
+            //
+            // unless you allow multiple API versioning methods in your application,
+            // your implementation should be even simpler.
+
+            // consider the url path segment parameter first
+            // note: in OData, the ApiVersionRouteConstraint always has the name "apiVersion" which cannot be changed
+            var parameter = parameters.SingleOrDefault( p => p.name == "apiVersion" || p.name == "api-version" );
+
+            if ( parameter == null )
+            {
+                // the only other method in this sample is by query string
+                parameter = new Parameter()
+                {
+                    name = "api-version",
+                    required = true,
+                    @in = "query",
+                    type = "string"
+                };
+
+                parameters.Add( parameter );
+            }
+
+            // update the default value with the current API version so that
+            // the route can be invoked in the "Try It!" feature
+            parameter.@default = description.ApiVersion.ToString();
+            parameter.description = "The requested API version";
+        }
+    }
+}

samples/webapi/SwaggerODataWebApiSample/Models/ApiVersions.cs

@@ -0,0 +1,12 @@
+namespace Microsoft.Examples.Models
+{
+    using Microsoft.Web.Http;
+    using System;
+
+    static class ApiVersions
+    {
+        internal static readonly ApiVersion V1 = new ApiVersion( 1, 0 );
+        internal static readonly ApiVersion V2 = new ApiVersion( 2, 0 );
+        internal static readonly ApiVersion V3 = new ApiVersion( 3, 0 );
+    }
+}

samples/webapi/SwaggerODataWebApiSample/Models/Order.cs

@@ -0,0 +1,36 @@
+namespace Microsoft.Examples.Models
+{
+    using System;
+    using System.ComponentModel.DataAnnotations;
+
+    /// <summary>
+    /// Represents an order.
+    /// </summary>
+    public class Order
+    {
+        /// <summary>
+        /// Gets or sets the unique identifier for the order.
+        /// </summary>
+        /// <value>The order's unique identifier.</value>
+        public int Id { get; set; }
+
+        /// <summary>
+        /// Gets or sets the date and time when the order was created.
+        /// </summary>
+        /// <value>The order's creation date.</value>
+        public DateTimeOffset CreatedDate { get; set; } = DateTimeOffset.Now;
+
+        /// <summary>
+        /// Gets or sets the date and time when the order becomes effective.
+        /// </summary>
+        /// <value>The order's effective date.</value>
+        public DateTimeOffset EffectiveDate { get; set; } = DateTimeOffset.Now;
+
+        /// <summary>
+        /// Gets or sets the name of the ordering customer.
+        /// </summary>
+        /// <value>The name of the customer that placed the order.</value>
+        [Required]
+        public string Customer { get; set; }
+    }
+}

samples/webapi/SwaggerODataWebApiSample/Models/Person.cs

@@ -0,0 +1,45 @@
+namespace Microsoft.Examples.Models
+{
+    using System;
+    using System.ComponentModel.DataAnnotations;
+
+    /// <summary>
+    /// Represents a person.
+    /// </summary>
+    public class Person
+    {
+        /// <summary>
+        /// Gets or sets the unique identifier for a person.
+        /// </summary>
+        /// <value>The person's unique identifier.</value>
+        public int Id { get; set; }
+
+        /// <summary>
+        /// Gets or sets the first name of a person.
+        /// </summary>
+        /// <value>The person's first name.</value>
+        [Required]
+        [StringLength( 25 )]
+        public string FirstName { get; set; }
+
+        /// <summary>
+        /// Gets or sets the last name of a person.
+        /// </summary>
+        /// <value>The person's last name.</value>
+        [Required]
+        [StringLength( 25 )]
+        public string LastName { get; set; }
+
+        /// <summary>
+        /// Gets or sets the email address for a person.
+        /// </summary>
+        /// <value>The person's email address.</value>
+        public string Email { get; set; }
+
+        /// <summary>
+        /// Gets or sets the telephone number for a person.
+        /// </summary>
+        /// <value>The person's telephone number.</value>
+        public string Phone { get; set; }
+    }
+}

samples/webapi/SwaggerODataWebApiSample/Properties/AssemblyInfo.cs

@@ -0,0 +1,35 @@
+using System.Reflection;
+using System.Runtime.CompilerServices;
+using System.Runtime.InteropServices;
+
+// General Information about an assembly is controlled through the following 
+// set of attributes. Change these attribute values to modify the information
+// associated with an assembly.
+[assembly: AssemblyTitle( "SwaggerODataWebApiSample" )]
+[assembly: AssemblyDescription( "" )]
+[assembly: AssemblyConfiguration( "" )]
+[assembly: AssemblyCompany( "" )]
+[assembly: AssemblyProduct( "SwaggerODataWebApiSample" )]
+[assembly: AssemblyCopyright( "Copyright ©  2017" )]
+[assembly: AssemblyTrademark( "" )]
+[assembly: AssemblyCulture( "" )]
+
+// Setting ComVisible to false makes the types in this assembly not visible 
+// to COM components.  If you need to access a type in this assembly from 
+// COM, set the ComVisible attribute to true on that type.
+[assembly: ComVisible( false )]
+
+// The following GUID is for the ID of the typelib if this project is exposed to COM
+[assembly: Guid( "f3986f7b-af76-43d1-a44f-303023a08cd3" )]
+
+// Version information for an assembly consists of the following four values:
+//
+//      Major Version
+//      Minor Version 
+//      Build Number
+//      Revision
+//
+// You can specify all the values or you can default the Revision and Build Numbers 
+// by using the '*' as shown below:
+[assembly: AssemblyVersion( "1.0.0.0" )]
+[assembly: AssemblyFileVersion( "1.0.0.0" )]