How to use AllowedFilterProperties and AllowedExpandProperties under ODataQueryOptionDescriptionContext

[SamGuoMsft]

Is there an existing issue for this?

• I have searched the existing issues

Describe the bug

Not sure it is a bug or not. But I have scenario that we only have limit properties can be used as expand and filter and would like to show as description in Swagger. I saw ODataQueryOptionDescriptionContext exposes AllowedFilterProperties and AllowedExpandProperties, since we only can set max depth and max node.
options.QueryOptions.Controller()
.Action( c => c.Get( default ) )
.Allow( Filter | Expand )
.AllowExpand( 2 )
.AllowFilter( 4 );

Would you mind to give any suggestions how I can use these two properties?

Expected Behavior

Having a way to use AllowedFilterProperties and AllowedExpandProperties.

Steps To Reproduce

No response

Exceptions (if any)

No response

.NET Version

7.0.100

Anything else?

No response

[commonsensesoftware]

For an example of how to use the ODataQueryOptionDescriptionContext, you can have a look at: DefaultODataQueryOptionDescriptionProvider. The default provider can be extended or replaced and configured via:

builder.Services
       .AddApiVersioning()
       .AddOData()
       .AddODataApiExplorer(options => options.DescriptionProvider = new MyProvider());

However, I think you are asking how do you set or otherwise populate AllowedFilterProperties and AllowedExpandProperties. This is a good question and it clearly is not all that obvious (but it's supposed to be).

A key goal is to minimize the amount of configuration required and use what you've already defined to populate the query options. The cases where you can explicitly set conventions are only meant to cover the documentation gaps where you can't otherwise specify the information. As an example, if you used ODataQuerySettings and ODataValidationSettings directly in a controller action, there is no other way to surface this information. These classes do not have a way to limit $filter or $expand property names, which is why you can't find a built-in extension method convention for them.

The way these values are specified is via Model Bound settings. They are configured as attributes on your model classes or set
using the fluent conventions when you configure the EDM. This is required for OData to enforce the policies. The API Versioning extensions are of aware of this and will pick them up and document them for you. It might seem clunky, but it would be weird (and bad) if a limited set of properties were specified in the documentation, but they weren't actually limited by OData. Most settings can be configured multiple ways, but this happens to be some that can only be done this way (unless I've made a mistake or things have changed).

For example, you can apply:

[Expand("NoExpand", ExpandType = SelectExpandType.Disabled)]

To disable expand on an entire type, enable selective members, and set maximum depth. If you don't want to use attributes, you can use the fluent API a la:

builder.EntitySet<Order>("Orders")
                .EntityType.Expand(6)
                .Expand(SelectExpandType.Disabled, "NoExpand");

No matter which approach you choose, the API Versioning extensions should detect it. If there's something I've missed or there's some other method you're using that I'm not aware of, please. share.

[SamGuoMsft]

The problem for us is our service want to just use a set of OData query ability rather than being an fully OData service, so we don't create EDM model and register when service is up. By looking at the source code, I think the easiest way is to extend DefaultODataQueryOptionDescriptionProvider and base on the ApiDescription under ODataQueryOptionDescriptionContext to set limit properties for each controller and action, otherwise need to rewrite entire ODataControllerQueryOptionsConventionBuilder and ODataActionQueryOptionsConventionBuilder(with T also).

[commonsensesoftware]

I see. You probably should have led with that. 😉 Things work a little different with some OData.

There are still a few options:

1. Create and add a custom IODataQueryOptionsConvention, which can be added to the default builder
2. Extend/customize the default ODataQueryOptionsConventionBuilder
3. Extend/customize the DefaultODataQueryOptionDescriptionProvider

The ODataQueryOptionDescriptionContext is ultimately just a monad to collect all the discovered information from standard OData attributes and settings. There isn't anything that special about it. If you have your own convention or you know what you're looking for (in your own code), then it's pretty straight forward to add the necessary ApiParameterDescription instances. For example, you could create your own attribute that you know to look for (ex: [AllowedProperties("...")]).

Admittedly, there is limited support for some OData. This is an area could use some additional enhancements.

[SamGuoMsft]

For the options you mentioned:

1. I though about to build my own ODataValidationSettingsConvention which is inherited from IODataQueryOptionsConvention, but if I do that, I need to write my own ODataActionQueryOptionsConventionBuilder and override the Build method from base class ODataActionQueryOptionsConventionBuilderBase. Would you mind to let me know how to add to the default builder?
   2 and 3 we already discussed above, and for the AllowedProperties attribute, yeap, as I mentioned by using ApiDescription, I will add attribute and use attribute to control it.

The other approaches which I can think:
4. by using Swagger OperationFilter with parameter and custom attribute to edit description.
5. I looked at edm model again, based on the code , if I dynamically generate an EDM, can I set into ActionDescriptor EndpointMetadata and still keep service as standard restful? Since otherwise I can't use model API version in that case.

[commonsensesoftware]

I haven't tried it E2E, but something like this should work:

Provide some way to define allowed properties. Attributes are one way.

[AttributeUsage( AttributeTargets.Method, AllowMultiple = false, Inherited = true )]
internal sealed class AllowedPropertiesAttribute : Attribute
{
   public AllowedPropertiesAttribute( string property, params string[] otherProperties )
   {
      var properties = new string[otherProperties.Length + 1];

      properties[0] = property;

      if ( otherProperties.Length > 0 )
      {
         Array.Copy( otherProperties, 0, properties, 1, otherProperties.Length );
      }

      Properties = properties;
   }

   public IReadOnlyList Properties { get; }
}

There's a few ways this might be used. Something like:

[EnableQuery(AllowedQueryOptions = AllowQueryOptions.Expand)]
[AllowedProperties("customer", "lineItems")]
public IActionResult Get(int id) => Ok();

Now you can create a convention that looks like:

internal sealed class AllowedPropertiesConvention : IODataQueryOptionsConvention
{
   private readonly ODataQueryOptionSettings settings;

   public AllowedPropertiesConvention(
      IODataQueryOptionDescriptionProvider descriptionProvider,
      IModelMetadataProvider modelMetadataProvider,
      ODataOptions option )
   {
      settings = new()
      {
         NoDollarPrefix = true,
         DescriptionProvider = descriptionProvider,
         DefaultQuerySettings = options.QuerySettings,
         ModelMetadataProvider = modelMetadataProvider,
      }
   }

   public void ApplyTo( ApiDescription apiDescription )
   {
      // applying the convention as endpoint metadata is probably a better way to do this
      // but it requires more initial setup
      var method = ((ControllerActionDescriptor) apiDescription.ActionDescriptor).MethodInfo;
      var enableQuery = method.GetCustomAttribute<EnableQueryAttribute>();
      var allowed = method.GetCustomAttribute<AllowedPropertiesAttribute>();

      if ( enableQuery == null || allowed == null )
      {
         return;
      }

      var queryOption = enableQuery.AllowedQueryOptions;

      switch ( enableQuery.AllowedQueryOptions )
      {
         case AllowedQueryOptions.Expand:
         case AllowedQueryOptions.Filter:
            break;
         default:
            return;
      }

      var context = new ODataQueryOptionDescriptionContext( apiDescription );

      for ( var i = 0; i < allowed.Properties.Count; i++ )
      {
         context.AllowedProperties.Add( allowed.Properites[i] );
      }

      var name = ( settings.NoDollarPrefix ? string.Empty : "$" ) +
                 option.ToString().ToLowerInvariant();
      var type = typeof( string );
      var description = settings.DescriptionProvider.Describe( queryOption, context );
      var parameter = new ApiParameterDescription()
      {
            IsRequired = false,
            ModelMetadata = new ODataQueryOptionModelMetadata(
                settings.ModelMetadataProvider,
                type,
                description ),
            Name = name,
            ParameterDescriptor = new()
            {
                Name = name,
                ParameterType = type,
            },
            Source = BindingSource.Query,
            Type = type,
        };

      apiDescription.Parameters.Add( parameter );
   }
}

Finally, since DI is needed to get some of the services to build out the convention, we need IConfigureOptions<T>:

public sealed class ODataConventionSetup : IConfigureOptions<ODataApiExplorerOptions>
{
   private readonly IModelMetadataProvider modelMetadataProvider;
   private readonly IOptions<ODataOptions> odataOptions;

   public ODataConventionSetup(
      IModelMetadataProvider modelMetadataProvider,
      IOptions<ODataOptions> odataOptions )
   {
      this.modelMetadataProvider = modelMetadataProvider;
      this.odataOptions = odataOptions;
   }

   public void Configure( ODataApiExplorerOptions options )
   {
      var convention = new AllowedPropertiesConvention(
         options.DescriptionProvider,
         modelMetadataProvider,
         odataOptions );

      options.QueryOptions.Add( convention );
   }
}

This might seem like a lot of ceremony, but the challenge is trying to add a convention where no convention exists. As I mentioned the existing functionality for the fluent conventions API is to have parity with ODataQuerySettings and ODataValidationSettings. Neither of these have a way to specify the properties allowed with $expand or $filter. I'm not opposed to supporting it as an enhancement, but it's not there today.

Another possible option is to use the current, albeit limited, support for $expand and $filter conventions and update the description after the parameter is added with the additional properties. Of course, you could go down the Swashbuckle or OpenAPI extensions, but you'll have many of the same challenges.

Hopefully that give you a few ideas.

[commonsensesoftware]

Yes, you could create a EDM just for the purposes of metadata. It would have no effect on the surface area of the API. You need to have the OData services and features enabled change the wire protocol. I haven't tried it, but it should be possible to use the EDM just to provide this documentation.