[ApiExplorerSettings(IgnoreApi = true)] isn't respected with ASP.NET Core applications using OData API Explorer

[jimmy3912msncom]

As the title mentions, [ApiExplorerSettings(IgnoreApi = true)] doesn't work for me.

I'm using the ASP.NET Core with OData API Explorer sample from https://github.com/Microsoft/aspnet-api-versioning/tree/master/samples/aspnetcore/SwaggerODataSample and adding the below line above the V1 OrdersController

...
[ApiExplorerSettings(IgnoreApi = true)]
public class OrdersController : ODataController
...

I assume this isn't by design and is something that just isn't supported yet?

[commonsensesoftware]

Actually, but perhaps to your surprise, this is by design. The ODataController base class already has the implementation:

[ODataFormatting]
[ODataRouting]
[ApiExplorerSettings(IgnoreApi = true)]
public abstract partial class ODataController : ControllerBase
{
  // omitted for brevity
}

This means that if you want to integrate with something like Swagger, all of the OData controllers that derive from ODataController would be ignored. As it would be unusual to not use ODataController as the base class (it's not actually a requirement), there needs to be a way to work around this issue or nothing is discovered by the API Explorer. This behavior is true in ASP.NET Web API and ASP.NET Core.

The root cause for this behavior is that the OData team(s) never provided first-class support for the API Explorer. As a result, API Versioning provides everything from the ground up. A guiding design principle has always been to make API Versioning bolt-on rather than make developers change the way they do things. To stay consistent with the design principles, but still provide this functionality, the OData API Explorer implementations ignore ApiExplorerSettingsAttribute.IgnoreApi property value by default.

Of course if the configured value was always ignored without any ability to change the behavior that would be limiting. If you want to honor the ApiExplorerSettingsAttribute.IgnoreApi, then you need only configure that in the API Explorer options:

services.AddODataApiExplorer( options => options.UseApiExplorerSettings = true );

This is also documented in the wiki topic Use API Explorer Settings.

Note that once you choose to honor the ApiExplorerSettingsAttribute.IgnoreApi, this will result in all other undecorated classes that inherit from ODataController to be ignored as well. To include them, you'll need to do one of following:

• Decorate your controllers with [ApiExplorerSettings(IgnoreApi = false)] to override the inherited value
• Create a new base class that includes [ApiExplorerSettings(IgnoreApi = false)] and use that instead of ODataController which isn't that special
  • You could subclass ODataController and just override [ApiExplorerSettings(IgnoreApi = false)], but that would be arguably an abuse of inheritance

I hope that helps.

[jimmy3912msncom]

@commonsensesoftware Thanks Chris, I guess I never saw that. I tried to enable it but it failed in the sample with The action 'Microsoft.Examples.V1.OrdersController.Get (SwaggerODataSample)' has ApiExplorer enabled, but is using conventional routing. Only actions which use attribute routing support ApiExplorer.

All I did to the sample was:

As you mentioned added the below to Startup:

services.AddODataApiExplorer(
   options =>
   {
      ...
      options.UseApiExplorerSettings = true;
      ...
   } );

And changed the IgnoreApi to false in OrdersController:

...
[ApiExplorerSettings(IgnoreApi = false)]
public class OrdersController : ODataController
...

[commonsensesoftware]

Ah … yes - this is because the built-in API Explorer for ASP.NET Core only supports attribute routing. I think it's possible to still make the OData bits work by convention. I need to review this some more. Should that be the case, then I'll consider this a bug in the OData API Explorer.

It seems you are using OData conventions only. I'm pretty sure if you use OData attribute routing, you can workaround this issue. I'm sure that's not the answer you're looking for, but it may be a workable solution to unblock yourself while I investigate this. Thanks.

[jimmy3912msncom]

@commonsensesoftware Correct me if I'm wrong but to my understanding the sample was using attribute based routing:

    ...
    [ApiVersion( "1.0" )]
    [ApiVersion( "0.9", Deprecated = true )]
    [ODataRoutePrefix( "Orders" )]
    public class OrdersController : ODataController
    {
        ...
        [Produces( "application/json" )]
        [ProducesResponseType( typeof( Order ), Status200OK )]
        [ProducesResponseType( Status404NotFound )]
        [ODataRoute( "({key})" )]
        public IActionResult Get( int key ) => Ok( new Order() { Id = key, Customer = "John Doe" } );
        ...

[commonsensesoftware]

In reviewing the sample, it actually has support for OData attribute and convention-based routing. I suspect that this may be a sequencing problem in the order the providers are configured. If you're curious, this is the place in ASP.NET Core that doesn't allow the API Explorer configuration if the attribute information is not available. I had to create a custom OData flavor of the route information parsed from the OData template. This is almost certainly a bug, but I want to verify first.

There are two interim workarounds (by leaving options.UseApiExplorerSettings = false):

• Create and register a custom IApiDescriptionProvider which filters out the actions you don't want
• Create a custom IOperationFilter to exclude operations you don't want in the Swagger document

Either approach will prevent the actions you don't want to discover from being present in the Swagger document. This is obviously not ideal, but it should work while I look into this futher.

[jimmy3912msncom]

Thanks Chris. I am already doing the latter with a custom filter but was hoping to use something out of box :)

[commonsensesoftware]

Good to know. It definitely should be working that way out-of-the-box, but I want to make sure you're unblocked first.