Add support for exploring OData metadata routes. Resolves #893

commonsensesoftware · commonsensesoftware · commit ea50eb241f23 · 2022-11-06T22:26:28.000-08:00
diff --git a/src/AspNet/OData/src/Asp.Versioning.WebApi.OData.ApiExplorer/ApiExplorer/ODataApiExplorer.cs b/src/AspNet/OData/src/Asp.Versioning.WebApi.OData.ApiExplorer/ApiExplorer/ODataApiExplorer.cs
@@ -82,6 +82,24 @@ protected override bool ShouldExploreAction(
             return base.ShouldExploreAction( actionRouteParameterValue, actionDescriptor, route, apiVersion );
         }
 
+        if ( actionDescriptor.ControllerDescriptor.ControllerType.IsMetadataController() )
+        {
+            if ( actionDescriptor.ActionName == nameof( MetadataController.GetServiceDocument ) )
+            {
+                if ( !Options.MetadataOptions.HasFlag( ODataMetadataOptions.ServiceDocument ) )
+                {
+                    return false;
+                }
+            }
+            else
+            {
+                if ( !Options.MetadataOptions.HasFlag( ODataMetadataOptions.Metadata ) )
+                {
+                    return false;
+                }
+            }
+        }
+
         if ( Options.UseApiExplorerSettings )
         {
             var setting = actionDescriptor.GetCustomAttributes<ApiExplorerSettingsAttribute>().FirstOrDefault();
@@ -112,9 +130,10 @@ protected override bool ShouldExploreController(
             throw new ArgumentNullException( nameof( route ) );
         }
 
-        if ( typeof( MetadataController ).IsAssignableFrom( controllerDescriptor.ControllerType ) )
+        if ( controllerDescriptor.ControllerType.IsMetadataController() )
         {
-            return false;
+            controllerDescriptor.ControllerName = "OData";
+            return Options.MetadataOptions > ODataMetadataOptions.None;
         }
 
         var routeTemplate = route.RouteTemplate;
diff --git a/src/AspNet/OData/src/Asp.Versioning.WebApi.OData.ApiExplorer/Routing/ODataRouteBuilder.cs b/src/AspNet/OData/src/Asp.Versioning.WebApi.OData.ApiExplorer/Routing/ODataRouteBuilder.cs
@@ -285,6 +285,25 @@ private void AppendPathFromConventions( IList<string> segments, string controlle
             case UnboundOperation:
                 builder.Append( Context.Operation!.Name );
                 AppendParametersFromConvention( builder, Context.Operation );
+                break;
+            default:
+                var action = Context.ActionDescriptor;
+
+                if ( action.ControllerDescriptor.ControllerType.IsMetadataController() )
+                {
+                    if ( action.ActionName == nameof( MetadataController.GetServiceDocument ) )
+                    {
+                        if ( segments.Count == 0 )
+                        {
+                            segments.Add( "/" );
+                        }
+                    }
+                    else
+                    {
+                        segments.Add( "$metadata" );
+                    }
+                }
+
                 break;
         }
 
diff --git a/src/AspNet/OData/src/Asp.Versioning.WebApi.OData.ApiExplorer/Routing/ODataRouteBuilderContext.cs b/src/AspNet/OData/src/Asp.Versioning.WebApi.OData.ApiExplorer/Routing/ODataRouteBuilderContext.cs
@@ -43,7 +43,9 @@ internal ODataRouteBuilderContext(
         ActionDescriptor = actionDescriptor;
         ParameterDescriptions = parameterDescriptions;
         Options = options;
-        UrlKeyDelimiter = UrlKeyDelimiterOrDefault( configuration.GetUrlKeyDelimiter() ?? Services.GetService<IODataPathHandler>()?.UrlKeyDelimiter );
+        UrlKeyDelimiter = UrlKeyDelimiterOrDefault(
+            configuration.GetUrlKeyDelimiter() ??
+            Services.GetService<IODataPathHandler>()?.UrlKeyDelimiter );
 
         var selector = Services.GetRequiredService<IEdmModelSelector>();
         var model = selector.SelectModel( apiVersion );
@@ -64,7 +66,8 @@ internal ODataRouteBuilderContext(
         Singleton = container.FindSingleton( controllerName );
         Operation = ResolveOperation( container, actionDescriptor );
         ActionType = GetActionType( actionDescriptor );
-        IsRouteExcluded = ActionType == ODataRouteActionType.Unknown;
+        IsRouteExcluded = ActionType == ODataRouteActionType.Unknown &&
+                         !actionDescriptor.ControllerDescriptor.ControllerType.IsMetadataController();
 
         if ( Operation?.IsAction() == true )
         {
diff --git a/src/AspNet/OData/test/Asp.Versioning.WebApi.OData.ApiExplorer.Tests/Description/ODataApiExplorerTest.cs b/src/AspNet/OData/test/Asp.Versioning.WebApi.OData.ApiExplorer.Tests/Description/ODataApiExplorerTest.cs
@@ -34,7 +34,10 @@ public void api_descriptions_should_group_versioned_controllers( HttpConfigurati
     {
         // arrange
         var assembliesResolver = configuration.Services.GetAssembliesResolver();
-        var controllerTypes = configuration.Services.GetHttpControllerTypeResolver().GetControllerTypes( assembliesResolver );
+        var controllerTypes = configuration.Services
+                                           .GetHttpControllerTypeResolver()
+                                           .GetControllerTypes( assembliesResolver )
+                                           .Where( t => !typeof( MetadataController ).IsAssignableFrom( t ) );
         var apiExplorer = new ODataApiExplorer( configuration );
 
         // act
@@ -54,7 +57,10 @@ public void api_descriptions_should_flatten_versioned_controllers( HttpConfigura
     {
         // arrange
         var assembliesResolver = configuration.Services.GetAssembliesResolver();
-        var controllerTypes = configuration.Services.GetHttpControllerTypeResolver().GetControllerTypes( assembliesResolver );
+        var controllerTypes = configuration.Services
+                                            .GetHttpControllerTypeResolver()
+                                            .GetControllerTypes( assembliesResolver )
+                                            .Where( t => !typeof( MetadataController ).IsAssignableFrom( t ) );
         var apiExplorer = new ODataApiExplorer( configuration );
 
         // act
@@ -86,6 +92,37 @@ public void api_descriptions_should_not_contain_metadata_controllers( HttpConfig
                     .NotContain( type => typeof( MetadataController ).IsAssignableFrom( type ) );
     }
 
+    [Theory]
+    [InlineData( ODataMetadataOptions.ServiceDocument )]
+    [InlineData( ODataMetadataOptions.Metadata )]
+    [InlineData( ODataMetadataOptions.All )]
+    public void api_descriptions_should_contain_metadata_controllers( ODataMetadataOptions metadataOptions )
+    {
+        // arrange
+        var configuration = TestConfigurations.NewOrdersConfiguration();
+        var options = new ODataApiExplorerOptions( configuration ) { MetadataOptions = metadataOptions };
+        var apiExplorer = new ODataApiExplorer( configuration, options );
+
+        // act
+        var groups = apiExplorer.ApiDescriptions;
+
+        // assert
+        for ( var i = 0; i < groups.Count; i++ )
+        {
+            var group = groups[i];
+
+            if ( metadataOptions.HasFlag( ODataMetadataOptions.ServiceDocument ) )
+            {
+                group.ApiDescriptions.Should().Contain( item => item.RelativePath == "api" );
+            }
+
+            if ( metadataOptions.HasFlag( ODataMetadataOptions.Metadata ) )
+            {
+                group.ApiDescriptions.Should().Contain( item => item.RelativePath == "api/$metadata" );
+            }
+        }
+    }
+
     [Theory]
     [ClassData( typeof( TestConfigurations ) )]
     public void api_description_group_should_explore_v3_actions( HttpConfiguration configuration )
diff --git a/src/AspNet/OData/test/Asp.Versioning.WebApi.OData.ApiExplorer.Tests/Description/TestConfigurations.cs b/src/AspNet/OData/test/Asp.Versioning.WebApi.OData.ApiExplorer.Tests/Description/TestConfigurations.cs
@@ -2,6 +2,7 @@
 
 namespace Asp.Versioning.Description;
 
+using Asp.Versioning.Controllers;
 using Asp.Versioning.Conventions;
 using Asp.Versioning.OData;
 using Asp.Versioning.Simulators.Configuration;
@@ -24,6 +25,7 @@ public static HttpConfiguration NewOrdersConfiguration()
     {
         var configuration = new HttpConfiguration();
         var controllerTypeResolver = new ControllerTypeCollection(
+            typeof( VersionedMetadataController ),
             typeof( Simulators.V1.OrdersController ),
             typeof( Simulators.V2.OrdersController ),
             typeof( Simulators.V3.OrdersController ) );
@@ -57,9 +59,10 @@ public static HttpConfiguration NewPeopleConfiguration()
     {
         var configuration = new HttpConfiguration();
         var controllerTypeResolver = new ControllerTypeCollection(
-           typeof( Simulators.V1.PeopleController ),
-           typeof( Simulators.V2.PeopleController ),
-           typeof( Simulators.V3.PeopleController ) );
+            typeof( VersionedMetadataController ),
+            typeof( Simulators.V1.PeopleController ),
+            typeof( Simulators.V2.PeopleController ),
+            typeof( Simulators.V3.PeopleController ) );
 
         configuration.Services.Replace( typeof( IHttpControllerTypeResolver ), controllerTypeResolver );
         configuration.AddApiVersioning();
@@ -79,8 +82,9 @@ public static HttpConfiguration NewProductAndSupplierConfiguration()
     {
         var configuration = new HttpConfiguration();
         var controllerTypeResolver = new ControllerTypeCollection(
-           typeof( Simulators.V3.ProductsController ),
-           typeof( Simulators.V3.SuppliersController ) );
+            typeof( VersionedMetadataController ),
+            typeof( Simulators.V3.ProductsController ),
+            typeof( Simulators.V3.SuppliersController ) );
 
         configuration.Services.Replace( typeof( IHttpControllerTypeResolver ), controllerTypeResolver );
         configuration.AddApiVersioning();
diff --git a/src/AspNetCore/OData/src/Asp.Versioning.OData.ApiExplorer/ApiExplorer/ODataApiDescriptionProvider.cs b/src/AspNetCore/OData/src/Asp.Versioning.OData.ApiExplorer/ApiExplorer/ODataApiDescriptionProvider.cs
@@ -16,6 +16,7 @@ namespace Asp.Versioning.ApiExplorer;
 using System.Diagnostics.CodeAnalysis;
 using System.Runtime.CompilerServices;
 using static System.StringComparison;
+using static ODataMetadataOptions;
 using Opts = Microsoft.Extensions.Options.Options;
 
 /// <summary>
@@ -118,11 +119,24 @@ public virtual void OnProvidersExecuted( ApiDescriptionProviderContext context )
             }
 
             if ( !TryMatchModelVersion( result, metadata, out var matched ) ||
-                 IsServiceDocumentOrMetadata( matched.Template ) ||
                  !visited.Add( result ) )
             {
                 results.RemoveAt( i );
             }
+            else if ( IsServiceDocument( matched.Template ) )
+            {
+                if ( !Options.MetadataOptions.HasFlag( ServiceDocument ) )
+                {
+                    results.RemoveAt( i );
+                }
+            }
+            else if ( IsMetadata( matched.Template ) )
+            {
+                if ( !Options.MetadataOptions.HasFlag( Metadata ) )
+                {
+                    results.RemoveAt( i );
+                }
+            }
             else if ( IsNavigationPropertyLink( matched.Template ) )
             {
                 results.RemoveAt( i );
@@ -176,8 +190,10 @@ private static int ApiVersioningOrder()
     }
 
     [MethodImpl( MethodImplOptions.AggressiveInlining )]
-    private static bool IsServiceDocumentOrMetadata( ODataPathTemplate template ) =>
-        template.Count == 0 || ( template.Count == 1 && template[0] is MetadataSegmentTemplate );
+    private static bool IsServiceDocument( ODataPathTemplate template ) => template.Count == 0;
+
+    [MethodImpl( MethodImplOptions.AggressiveInlining )]
+    private static bool IsMetadata( ODataPathTemplate template ) => template.Count == 1 && template[0] is MetadataSegmentTemplate;
 
     [MethodImpl( MethodImplOptions.AggressiveInlining )]
     private static bool IsNavigationPropertyLink( ODataPathTemplate template ) =>
diff --git a/src/AspNetCore/OData/src/Asp.Versioning.OData/Controllers/VersionedMetadataController.cs b/src/AspNetCore/OData/src/Asp.Versioning.OData/Controllers/VersionedMetadataController.cs
@@ -14,6 +14,7 @@ namespace Asp.Versioning.Controllers;
 /// </summary>
 [CLSCompliant( false )]
 [ReportApiVersions]
+[ControllerName( "OData" )]
 public class VersionedMetadataController : MetadataController
 {
     /// <summary>
diff --git a/src/AspNetCore/OData/test/Asp.Versioning.OData.ApiExplorer.Tests/ApiExplorer/ODataApiDescriptionProviderTest.cs b/src/AspNetCore/OData/test/Asp.Versioning.OData.ApiExplorer.Tests/ApiExplorer/ODataApiDescriptionProviderTest.cs
@@ -56,6 +56,62 @@ public void odata_api_explorer_should_group_and_order_descriptions_on_providers_
         AssertVersion3( groups[3] );
     }
 
+    [Theory]
+    [InlineData( ODataMetadataOptions.ServiceDocument )]
+    [InlineData( ODataMetadataOptions.Metadata )]
+    [InlineData( ODataMetadataOptions.All )]
+    public void odata_api_explorer_should_explore_metadata_routes( ODataMetadataOptions metadataOptions )
+    {
+        // arrange
+        var builder = new WebHostBuilder()
+            .ConfigureServices(
+                services =>
+                {
+                    services.AddControllers()
+                            .AddOData(
+                                options =>
+                                {
+                                    options.Count().Select().OrderBy();
+                                    options.RouteOptions.EnableKeyInParenthesis = false;
+                                    options.RouteOptions.EnableNonParenthesisForEmptyParameterFunction = true;
+                                    options.RouteOptions.EnableQualifiedOperationCall = false;
+                                    options.RouteOptions.EnableUnqualifiedOperationCall = true;
+                                } );
+
+                    services.AddApiVersioning()
+                            .AddOData( options => options.AddRouteComponents( "api" ) )
+                            .AddODataApiExplorer( options => options.MetadataOptions = metadataOptions );
+
+                    services.TryAddEnumerable( ServiceDescriptor.Transient<IApplicationModelProvider, TestApiExplorerApplicationModelProvider>() );
+                } )
+            .Configure( app => app.UseRouting().UseEndpoints( endpoints => endpoints.MapControllers() ) );
+        var host = builder.Build();
+        var serviceProvider = host.Services;
+
+        // act
+        var groups = serviceProvider.GetRequiredService<IApiDescriptionGroupCollectionProvider>()
+                                    .ApiDescriptionGroups
+                                    .Items
+                                    .OrderBy( i => i.GroupName )
+                                    .ToArray();
+
+        // assert
+        for ( var i = 0; i < groups.Length; i++ )
+        {
+            var group = groups[i];
+
+            if ( metadataOptions.HasFlag( ODataMetadataOptions.ServiceDocument ) )
+            {
+                group.Items.Should().Contain( item => item.RelativePath == "api" );
+            }
+
+            if ( metadataOptions.HasFlag( ODataMetadataOptions.Metadata ) )
+            {
+                group.Items.Should().Contain( item => item.RelativePath == "api/$metadata" );
+            }
+        }
+    }
+
     private readonly ITestOutputHelper console;
 
     public ODataApiDescriptionProviderTest( ITestOutputHelper console ) => this.console = console;
diff --git a/src/Common/src/Common.OData.ApiExplorer/ApiExplorer/ODataApiExplorerOptions.cs b/src/Common/src/Common.OData.ApiExplorer/ApiExplorer/ODataApiExplorerOptions.cs
@@ -38,4 +38,10 @@ public ODataQueryOptionsConventionBuilder QueryOptions
         get => queryOptions ??= new();
         set => queryOptions = value;
     }
+
+    /// <summary>
+    /// Gets or sets the OData metadata options used during API exploration.
+    /// </summary>
+    /// <value>One or more <see cref="ODataMetadataOptions"/> values.</value>
+    public ODataMetadataOptions MetadataOptions { get; set; } = ODataMetadataOptions.None;
 }
diff --git a/src/Common/src/Common.OData.ApiExplorer/ApiExplorer/ODataMetadataOptions.cs b/src/Common/src/Common.OData.ApiExplorer/ApiExplorer/ODataMetadataOptions.cs
@@ -0,0 +1,30 @@
+// Copyright (c) .NET Foundation and contributors. All rights reserved.
+
+namespace Asp.Versioning.ApiExplorer;
+
+/// <summary>
+/// Represents the possible OData metadata options used during API exploration.
+/// </summary>
+[Flags]
+public enum ODataMetadataOptions
+{
+    /// <summary>
+    /// Indicates no OData metadata options.
+    /// </summary>
+    None = 0,
+
+    /// <summary>
+    /// Indicates the OData service document will be included.
+    /// </summary>
+    ServiceDocument = 1,
+
+    /// <summary>
+    /// Indicates the OData metadata document will be included.
+    /// </summary>
+    Metadata = 2,
+
+    /// <summary>
+    /// Indicates all OData metadata options.
+    /// </summary>
+    All = ServiceDocument | Metadata,
+}
diff --git a/src/Common/src/Common.OData/TypeExtensions.cs b/src/Common/src/Common.OData/TypeExtensions.cs
@@ -28,7 +28,7 @@ internal static partial class TypeExtensions
 
     internal static bool IsODataController( this Type controllerType ) => controllerType.UsingOData();
 
-    internal static bool IsMetadataController( this TypeInfo controllerType )
+    internal static bool IsMetadataController( this Type controllerType )
     {
         metadataController ??= typeof( MetadataController );
         return metadataController.IsAssignableFrom( controllerType );

Original file line number	Diff line number	Diff line change
`@@ -14,6 +14,7 @@ namespace Asp.Versioning.Controllers;`
`14`	`14`	`/// </summary>`
`15`	`15`	`[CLSCompliant( false )]`
`16`	`16`	`[ReportApiVersions]`
	`17`	`+[ControllerName( "OData" )]`
`17`	`18`	`public class VersionedMetadataController : MetadataController`
`18`	`19`	`{`
`19`	`20`	`/// <summary>`
Original file line number	Diff line number	Diff line change
`@@ -38,4 +38,10 @@ public ODataQueryOptionsConventionBuilder QueryOptions`
`38`	`38`	`get => queryOptions ??= new();`
`39`	`39`	`set => queryOptions = value;`
`40`	`40`	`}`
	`41`	`+`
	`42`	`+ /// <summary>`
	`43`	`+ /// Gets or sets the OData metadata options used during API exploration.`
	`44`	`+ /// </summary>`
	`45`	`+ /// <value>One or more <see cref="ODataMetadataOptions"/> values.</value>`
	`46`	`+ public ODataMetadataOptions MetadataOptions { get; set; } = ODataMetadataOptions.None;`
`41`	`47`	`}`