I'm confused regarding OData + ApiExplorer

[julealgon]

It has always been a pain to integrate Swagger with OData. A few years ago, you'd need to manually ignore OData controllers, modify input and output formatters, etc.

The situation seems to have improved slightly, but is still far from ideal. When using latest versions of OData and Swashbuckle, you still get zero docs regarding ODataQueryOptions, return types are messed up, Delta<T> is not properly described, etc.

My understanding is that this library here fixes some of those problems, including allowing one to describe the query options per action/controller which then shows up properly in ApiExplorer and thus Swagger (at least that's what I'm seeing in the code examples).

However, this is a versioning library mainly, and not an ApiExplorer/Swagger one.... I'm currently a bit confused about how I'd go to get "proper" swagger docs for OData without using versioning at all. My impression is that this library here is conflating both things, making it a requirement to have versioning in place before the various ApiExplorer OData enhancements can be used. What if I don't care about versioning, but I want a consistent swagger doc?

Am I missing something here? Is it possible to get proper ODataQueryOptions, Delta, etc docs in Swagger without necessarily enabling API Versioning? If not, why? Wouldn't it be best if ApiExplorer and versioning concerns were separate from each other, to allow people to consume only one or the other (or both)?

My quick attempt at "converting" a standard OData v8 test project here to use the 6.0.3 preview of Api.Versioning has now been very smooth... lots of things have changed dramatically between standard OData and the "API Versioning version of OData" (if you could even call it that), in particular how the EDM is generated and provided to the framework (this library seems to have completely shifted how that works by forcing one to implement configuration interfaces on a per-entity basis, kinda like EFCore config classes?).

I apologize if I'm missing something obvious. I've been keeping track of this not so much for the versioning aspects but for the whole OData swagger compliance aspect. I had not used the library for versioning before so a ton of the concepts escape me. I was hoping I'd be able to tap into the ApiExplorer OData enhancements here without paying much attention to the versioning parts but it appears I was wrong: even the "simple" samples using the preview version actually seem quite complex to me even if only due to the dramatic change in how EDM is configured.

Any help or clarification is appreciated.

[commonsensesoftware]

You are correct that is there is some overlap and conflation. There's a long history of that with the team. For years, I've tried to convince them to support the API Explorer across the board. This would make integration with OpenAPI generators and many other scenarios seamless. They hear me, but they aren't listening. Enough people have complained or asked about it that there have been incremental improvements to OpenAPI support, but it's still OData (via EDM) → OpenAPI. There is an experimental library/repo highlighting the latest developments on that: OpenAPI.NET.OData.

One of the many areas that is a problem in is what happens when you have OData mixed with non-OData APIs? The EDM → OpenAPI approach doesn't work well for that (if at all). If the API Explorer was properly supported for OData it would a non-issue. Furthermore, there are still a lot of ASP.NET Web API and OData users. It's unclear if any of the new enhancements will help with that, but I won't be surprised if it doesn't.

I was involved in early discussions for 8.0, but my feedback seemingly fell on deaf ears. The OData design continues to center around a single EDM model for an application. They tried to convince me to put everything in a single EDM and I've had to reiterate many times how that doesn't really work and is overly complex. I can't say it was from my suggestions or guidance, but they did move to a model where the OData route information is computed up front, which is what API Versioning was doing before (albeit a different way) and how the API Explorer was supported at all. That is mostly a good thing, but there are issues with the design that make it difficult to apply versioning to. The most glaring of those is that there is one EDM per route prefix. Their idea of versioning is to have a prefix of v1, v2, etc, which is prescriptive and isn't RESTful. If you want to use any other method of versioning, it's non-trivial to make work (without API Versioning). The OData configuration has always had limited or closed extension points, which have required me to reimplement things. When I've been backed into those positions, my goal is to make the versioned variation feel as natural and as inline with the vanilla OData configuration as possible.

You are absolutely not forced to use configuration interfaces at all; that is purely a convenience. In fact, you don't even have to use the provided VersionedODataModelBuilder. The one and only requirement is that you provide a sequence of IEdmModel which has the ApiVersionAnnotation applied to the entire model. That's how API Versioning knows which EDM applies to which API version. In fairness, there is an opposite assumption that every API version will have its own, separate EDM (if at all), but that seems logical and highly, highly probable. The consequence of that assumption means you might have one or more EDMs than absolutely necessary.

The VersionedODataModelBuilder doesn't extend anything. It's basically just some glue that collates different parts together. The basic idea is to:

1. Collate all API versions
2. Create an ODataModelBuilder per API version using a factory
3. Provide a callback for each API version and route prefix combination for a constructed ODataModelBuilder
4. Apply the ApiVersionAnnotation for each constructed IEdmModel

The one thing I didn't want to do is recreate the ODataModelBuilder or any of its extensions. Again, it should feel like a normal OData configuration. I realized that EDM configurations, especially with versioning, could get large and you'd want to break them apart. IModelConfiguration affords that, but it's not a requirement (and - yes - it was inspired by EF 😉). Since IModelConfiguration is well-known, all implementations can be automatically discovered through DI. If you didn't want to do that, you can use a default callback like so:

var builder = new VersionedODataModelBuilder()
{
    DefaultModelConfiguration = (builder, version, prefix) => {  },
};

If you didn't want to use VersionedODataBuilder at all, then you might have something like:

var versions = new ApiVersion[]{ new(1.0), new(2.0), new(3.0) };
var models = new List<IEdmModel>();

for (var i = 0; i < versions.Length; i++)
{
    var version = versions[i];
    var builder = new ConventionsODataModelBuilder();
    
    // TODO: use builder normally
    
    var model = builder.GetEdmModel();
    
    model.SetAnnotationValue(model, new ApiVersionAnnotation(version));
    models.Add(model);
}

Ultimately, you are right, it would be nice and should be the case that there is comprehensive support for these things in OData without API Versioning, but it doesn't exist. I've been a big fan of the OData protocol for a long, long time. That's probably the only reason it is supported at all. I'm sure someone would have asked for it eventually, but most others probably would not have supported it.

My priority and goals are to API Versioning customers first. I am not opposed to a generic implementation that doesn't require API Versioning, but it's not my goal. I publicly stated in OData #332 that I would support the effort, but the response even from Sam and Mike was 🦗🦗🦗; they know me (I see that you ❤️ 'd it though 😉 ). Despite claims of being open source and accepting PRs, there is a history (still evident today) of long-running PRs that don't get reviewed or merged. That's why the InputFormatter and OutputFormatter issue (which I reported) took so long to be done. I'm not about to put a bunch of effort in and 🤞🏽 that it might get merged some day. Even getting 🐞 fixed and published can be like pulling 🦷 . If there is agreement and direction, I'm happy to contribute. A bunch of others have tried or partially ported my implementation without versioning.

Fortunately, this work could be peeled off into a new repo and library. If there are some collaborators, I could get behind that. I've been hesitant to own OData stuff because it seems to fluctuate significant since each major release. I don't have that much extra capacity to adapt to all of that. I don't want to own it. The product team should own it. Another issue is that I continue to support and have parity between ASP.NET Core and ASP.NET Web API where others seems to be content with leaving the Web API users behind. Any solution should support both.

Perhaps I can consider revisiting this for the 7.0 release and split it off into a new library. 🤔

[julealgon]

Thank you so much for such comprehensive response. As you know by now, I appreciate the work you have done/still do so much: you single-handedly are pushing for a lot of stuff to keep OData alive, and as a fellow fan of the protocol myself, I'm very happy for that. OData is criminally underrated its not even funny.

It really pains me that the OData support is so unstable... as you said, every new major version introduces dramatic changes and a brand new set of bugs and it seems we are not progressing much forward because of that. However, I'm noticing more engagement lately with v8 than previous versions, so I'm hopeful this will change and the platform will stabilize a bit more going forward. V8 is also standardizing a lot of stuff that was previously totally custom (i.e. routing) so that's also pretty good.

I'll definitely take a look at your code suggestions in more detail. I currently don't have a versioning requirement, but I still wanted to have "proper" swagger support for the OData actions. When I started trying to adapt my application I ran into a lot of new concepts at the same time and that's what confused me. Your explanation now makes sense... I totally understand that your main focus is on versioning itself and that's why all OData-related stuff here is built on top of the base versioning library. I can also relate to the fact that you don't want to own OData-specific scope... totally agree this should be on the OData product team.

Also, while I mentioned the IModelConfiguration as some sort of annoyance/hurdle in the OP, I actually vastly prefer that over building a monolithic EDM like what standard OData recommends. Have you considered trying to push your approach to the OData team as "the de-facto way of configuring EDM moving forward"? It is a lot more DI-friendly, less manual approach and also matches similar use cases like EF, so people would already be used to it. If there is already an issue for this, please share the link as I'd be interested in joining the discussion.

One thing that would be nice to see as another sample would be a "simple, single-version OData API" sample. Say, you are starting a project now and you don't yet know if you'll need versioning, but you want to get the basics in place to support it in the future. This sample wouldn't necessarily need to leverage every feature (like the model config interface, or the versioned builder, etc) and would be a nice way to migrate towards versioning without too many breaking changes from a standard OData API.

And perhaps in the Wiki, there could be some sort of "migration guide" for moving from a non-versioned OData API to a versioned one: what steps are needed, how to change the configuration, etc. That could help people coming to the library for the first time to leverage it properly.

Perhaps I can consider revisiting this for the 7.0 release and split it off into a new library. 🤔

If only from an architecture perspective, this would be very interesting. If there was a way to cleanly isolate ApiExplorer stuff from Versioning stuff so that one could use just the ApiExplorer extensions, I think there would be a lot of benefit there. It would also make it easier to port the ApiExplorer-exclusive stuff to the main OData repo I imagine (as there would naturally be less dependency on versioning concerns on it).

For example, today to add the OData ApiExplorer extensions, you have to do so after calling AddVersioning. I'd imagine that in a perfect world, you could just add ODataApiExplorer stuff by itself and it would still work properly.

I fully understand though that this would be additional effort on your side to support... ideally the OData team should take over it :(

[commonsensesoftware]

The wiki and documentation definitely needs some ❤️ with all the latest changes. It's coming, but there's just been other priorities. I'm looking at other possibilities besides the wiki. I'm getting close to what is feasible with a wiki. A more comprehensive migration guide would certainly be nice.

I don't have much issue with adding more examples. It can be a bit tricky to show "here's how you support this scenario" versus "this is what you should do". AllowDefaultVersionWhenUnspecified is an example of something that is often misunderstood and misused for purposes other than it was intended for. I'll see about adding something.

There's no open issue for something like IModelConfiguration in OData. Based on previous discussions, I curious what the reaction would. I wouldn't be surprised if there was resistance or low interest. The approach would be interesting for non-versioned scenarios, but I'm not sure there is a complete overlap with API versioning. The API Versioning approach calls back for each API version and route prefix combination, whereas OData only needs the route prefix. You certainly want the API version value to make decisions. With some more thought it might be possible, but it would require some buy-in on the OData side. It's not entirely clear to me if it's the team/repo that supports the EDM and URL parsing or if it's the ASP.NET Core team/repo. I believe they are different teams. There might be a few members that work on both.

A lot of the API Explorer support was a built by or required work I added in API Versioning. Splitting it over properly also meant forking code and maintaining two copies of it. In other ways, it was an initial playground to flush out what the design would look like and how it would ultimately work. Now that things have had a chance to burn-in and there have been improvements in OData, it may make sense to break things off. My only other consideration is keeping as much parity as feasibly possible with Web API, which continues to live on.