Feature: Implement ASP.NET Core OData v8 with Swagger/OpenAPI

[PoulSteffensen]

Summary
Integrate ASP.NET Core OData v8 into the Web API project of dotnet-starter-kit and expose OData endpoints through Swagger/OpenAPI. This gives clients rich, standardized query capabilities ($filter, $select, $expand, $orderby, $top, $skip, $count) while keeping our API surface minimal and discoverable via Swagger UI. Implementation follows Microsoft's OData guidance and Swashbuckle setup for ASP.NET Core.

---

Why this belongs in dotnet-starter-kit

• Powerful querying with fewer endpoints: Built-in OData query options reduce the need for custom endpoints and fit admin/back-office/reporting scenarios.
• Modern, supported stack: ASP.NET Core OData v8 is actively maintained; OData .NET 8 modernizes internals on recent .NET versions.
• Discoverability via Swagger/OpenAPI: Swashbuckle provides interactive docs; newer ASP.NET Core templates require explicit OpenAPI/Swagger configuration.

References

• OData Fundamentals (ASP.NET Core OData 8): https://learn.microsoft.com/en-us/odata/webapi-8/fundamentals/overview
• Getting Started with OData 8: https://learn.microsoft.com/en-us/odata/webapi-8/getting-started
• OData Query Options: https://learn.microsoft.com/en-us/odata/webapi-8/fundamentals/query-options
• OData .NET 8 Announcement: https://devblogs.microsoft.com/odata/announcing-odata-net-8-official-release/
• Swashbuckle with ASP.NET Core: https://learn.microsoft.com/en-us/aspnet/core/tutorials/getting-started-with-swashbuckle

---

Scope (for this repository)

Projects/paths
Assume the Web API entry point is src/apps/webapi/Program.cs. We’ll update docs if paths differ.

1. Add OData package

   • Add Microsoft.AspNetCore.OData to the Web API project.

2. Register OData services & EDM

   • Build an EDM model (ODataConventionModelBuilder) and register route components under /odata.
   • Enable query options: .Select().Filter().OrderBy().Expand().Count().SetMaxTop(null).

3. Create sample controller(s)

   • Inherit from ODataController and annotate GET actions with [EnableQuery].

4. Wire up Swagger/OpenAPI

   • Add Swashbuckle packages, then AddSwaggerGen(), UseSwagger(), UseSwaggerUI() in Program.cs.
   • Confirm OData endpoints operate and Swagger loads without formatter conflicts (workarounds exist if needed).

5. Documentation

   • Update kit docs (e.g., /docs or README) with examples & screenshots:
     • GET /odata/Products?$filter=Price gt 20
     • GET /odata/Products?$select=Id,Name&$orderby=Name
     • GET /odata/Products?$expand=Category&$count=true

---

Proposed Implementation (starter-kit aligned)

src/apps/webapi/Program.cs (illustrative—adapt to actual path/namespaces)

using Microsoft.AspNetCore.OData;
using Microsoft.OData.ModelBuilder;

var builder = WebApplication.CreateBuilder(args);

// Swagger / OpenAPI
builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen();

// OData EDM
var odataModelBuilder = new ODataConventionModelBuilder();
// Replace with a real entity from the kit (e.g., Products, Tenants, Users)
odataModelBuilder.EntitySet<Product>("Products");

builder.Services
    .AddControllers()
    .AddOData(opt => opt
        .Select().Filter().OrderBy().Expand().Count().SetMaxTop(null)
        .AddRouteComponents("odata", odataModelBuilder.GetEdmModel()));

var app = builder.Build();

if (app.Environment.IsDevelopment())
{
    app.UseSwagger();
    app.UseSwaggerUI();
    // Optional: app.UseODataRouteDebug(); // exposes ~/$odata routing page
}

app.UseRouting();
// keep existing auth/tenant middleware as-is
app.MapControllers();

[iammukeshm]

Quick Question, are you using the older version of FSH? I have recently re-written the entire repo, and it's on .NET 10. I noticied it from the code paths. Could you please confirm?

[PoulSteffensen]

Sorry, that's a mistake, please add the feature in the new .NET 10 version.

[maxiar]

Hi All! @PoulSteffensen , I know a little the OData protocol, but why OData instead GraphQL?

[PoulSteffensen]

OData and GraphQL are both queryable API technologies, but they serve different purposes and excel in different scenarios.

https://blog.bitsrc.io/choosing-between-graphql-vs-odata-api-823856bce8c2

For us, the main reason is ease of use, both in backend and frontend.

[iammukeshm]

Thanks for the detailed proposal! v10 uses Scalar + the built-in .NET OpenAPI stack (no Swashbuckle/Swagger), so this issue's Swashbuckle-based approach no longer applies as written. Closing for the v10 baseline — if you'd like OData support evaluated for v10, please open a fresh feature request and we'll triage it.

[PoulSteffensen]

Thanks, but it will not be necessary.