odata query options (filter/skip/top/orderby) not included in api explorer

[engenb]

Is there an existing issue for this?

• I have searched the existing issues

Describe the bug

I've tried to configure query options globally, via controller action attribute, the new ODataApiExplorerOptions approach and everything else I can think of. regardless, the only two odata query options that I've ever seen included in the api explorer are select and expand - I'm validating this via swagger.

Expected Behavior

configured query options should be included in openapi / swagger doc

Steps To Reproduce

here is a sample repo that demonstrates the issue

Exceptions (if any)

No response

.NET Version

8.0

Anything else?

I've also noticed the only api doc in swagger is v1 - v2 is excluded for some reason. I have not seen this issue before so not sure if it's related or not.

I'm working on migrating from Microsoft.AspNetCore.Mvc.Versioning.ApiExplorer

[commonsensesoftware]

The ODataApiExplorerOptions have been there a long time, even in the old Microsoft.AspNetCore.OData.Versioning.ApiExplorer.

There's a lot going on this in this project, but this could be the expected behavior. filter, skip, top, and orderby are all nonsensical for a scalars type (e.g. single entity or complex type). This would be the for any API that returns one result by key. Obviously, entity sets and functions should not be so limited. There's not much sense in including all of the query option noise for options that are either unsupported or will have no effect.

A few other notes:

1. You don't need [ApiController] since you're using OData; in fact, that might cause undesirable side effects
2. You're organizing by namespace, you could:
   a. Drop the V# suffix so that you don't need ControllerName
   b. Use the VersionByNamespaceConvention, which would negate the need for [ApiVersion]

I'll have to pull this down and go through it more, but that may be a few quick hints to try a few other things.

[engenb]

yeah, sorry if there's a bit of unrelated noise in the project. I wanted to set it up following a trimmed-down version of my typical microservice project template, so there might still be some concepts in there that are irrelevant. let me know if it's too noisy and I'll see if I can trim more of the fat.

some relevant concepts:

• this is a versioned odata api (of course)
• I've found it helpful to have a project-per-api-version, so adding new versions and removing old versions is as much "plug and play" as possible.
  • ^ means controller-per-version is likely a hard constraint
  • ideally, odata model configuration is also per-version. the new IModelConfiguration looks perfect for this
• for design/architecture reasons, I can't directly return my entity through the api. I'm utilizing AutoMapper.Extensions.OData to map the ODataQueryOptions from my api contracts to my entities.
  • I've found a db view-per-version can simplify this
  • also establishes a versioned "contract" for my downstream data warehouse team, currently extracting data from my database via Azure Data Factory.
  • I don't know if this is creating OData and ApiExplorer convention-based challenges because my controller actions all return IActionResult and never IQueryable<TEntity>
  • in order to use this project's predecessor, I ended up implementing my own AttributeRoutingConvention and IApiDescriptionProvider that just always added all the query parameters if the action had a ODataQueryOptiosn<> parameter. pretty brute force and not very elegant, but I decided better to have irrelevant options in swagger than not have needed options (I am not suggesting this as a solution for this framework)
    • ^ to adopt this project, I'd like to avoid having do that again
    • I'm completely open and ready to accept the goals of my project are just not compatible with the approach taken by this framework

[commonsensesoftware]

This is actually insightful and really useful information.

If you're using per-controller or per-project API versioning, the VersionByNamespaceConvention can really remove a lot of touch points. For example:

First you setup:

builder.Services
       .AddApiVersioning()
       .AddMvc(options => options.Conventions.Add(new VersionByNamespaceConvention()));

If all of your controllers are APIs, you can apply the conventions for all of them at once (and with no inheritance!):

// all controllers in here are API controllers
[assembly: ApiController]

then you can have:

//                    ↓ the API version derives from this
namespace Example.Api.V1.Controllers
{
    // [ApiVersion(1.0)] ← no longer required because it comes from the namespace
    // [ApiController] ← not required if you apply it to the entire assembly
    [Route("[controller]")]
    public class ExampleController : ControllerBase
    {
        [HttpGet]
        public IActionResult Get() => Ok();
    }
}

The wiki has more documentation the version by namespace convention

You are correct that the EDM is always per API version. It would be a soupy mess if it weren't that way.

Based on your description, it seems your services fall into the category of some OData. This typically entails using the query capabilities of OData, but not necessarily adhering to compliance with the protocol. This is allowed and supported. There's a few things that are slightly different from full OData because the intrinsic conventions aren't there. You may have a better time and more flexibility using that approach. You essentially just have regular 'ol controllers, that you use OData queries (and options) on, but nothing else. The IModelConfiguration only comes into play for the API Explorer, which is what feeds OpenAPI. The EDM is ephemerally built for exploration and is then discarded because that's the only time it's needed.

The OpenAPI with Some OData example will provide a working example with support for the API Explorer, OpenAPI, and the Swagger UI.

Happy to answer more questions.

[commonsensesoftware]

Following up. Did this actually solve your problem and unblock you or is there more to investigate?

[commonsensesoftware]

I believe I found the issue to the OP. This appears to be very similar to the scenario in #1110.

You have defined a custom ODataCollectionResponseType to represent the correct shape of an OData response. Unfortunately, OData doesn't provide anything out-of-the-box that I'm aware for this. The API Explorer extensions also provide an extensible type for this purpose a la ODataValue. This type only supports the value property by default, but it can be extended through inheritance if you want more.

The catch is that the API Explorer has a limited number of ways that it can understand the response type. You clearly understand that you can use the ProducesResponseTypeAttribute, but it gets more nuanced after that. Not every OData query option is applicable to all scenarios. $skip and $top, for example, are irrelevant and nonsensical for a scalar value such as a single entity, complex type, or raw value. If you enable these at a global or entity type level, it would be painful to have to continue to configure unapplicable query options to be ignored. The API Explorer is smart enough to understand that, even when enabled, query options that do not apply should not be explored.

Now we get to the rub. The API Explorer makes a lot of liberties to allow any scalar type or any multi-value response that implements IEnumerable. The formal OData response is a special case. It has a particular shape, but it can still be scalar or with an array of items. I've yet to come up with a completely generic solution. The current approach is to use ODataValue<T>, which is why it is provided by the library. The API Explorer knows that it if sees this specific variant, it needs to drill down into T to determine if the value is scalar or multi-value (e.g. ODataValue<T> or ODataValue<IEnumerable<T>>). This is only for the purposes of documentation and has no bearing on runtime behavior. The downside of this approach is that a specific type or subclass of it must be specified. That isn't always intrinsically obvious. I considered using an interface, but the type is never constructed so it doesn't really work unless you have something like IODataValue<T>, where you can interogate T. Beyond that, it's just a marker interface. I also realized that every single implementation would always have at least the value property and it would also be for JSON. Rather than make some reimplement that every time, I opted to go with a base class that can be extended as needed. Sadly, this is not super obvious to extenders. I do use this setup in the examples, but I'm sure plenty of people still miss it.

Long story short, I swapped out your ODataCollectionResponseType<T> with ODataValue<IEnumerable<T>> or ODataValue<T> as appropriate and things appeared to work and display as expected. Apologies for the overdue response; especially, since you provided a repro. I'm open to other ideas so to how to improve this behavior going forward.

[engenb]

wow thank you for digging into this and for such a comprehensive explanation. I'll make these updates as soon as possible and report back. I've been wanting to get on your latest and greatest.

the ODataCollectionResponseType was likely introduced because older versions of ODataValue weren't generic. this abstraction to model response shapes was carried forward to new projects and I'm sure I didn't notice sample usages of a generic ODataValue<T>.

thanks again for chasing this down!