Exhaustive OData Navigation Path Generation Problem

[christopinka]

OpenAPI Spec is 35MB Due to Exhaustive OData Navigation Path Generation
Problem:
The generated OpenAPI spec (v1.0) is 35MB with 10,405 paths, making it unusable in API clients (Insomnia, Postman, Swagger UI). The root cause is that the spec includes every possible navigation path through the object graph, not just useful endpoints.

Example of Path Explosion:
A single resource like /drives/{id}/items/{id} generates 1,505 paths because it includes every nested relationship:

/drives/{id}/items/{id} - the actual file (useful)

/drives/{id}/items/{id}/createdByUser - navigate to creator

/drives/{id}/items/{id}/createdByUser/manager - creator's manager

/drives/{id}/items/{id}/createdByUser/manager/directReports/{id} - manager's team

/drives/{id}/items/{id}/createdByUser/manager/directReports/{id}/photo - their photos

... continues 5-10 levels deep

Reality Check:
Nobody uses /drives/{id}/items/{id}/createdByUser/manager/photo - they'd call /users/{id}/photo directly. These navigation paths are technically valid in OData but practically useless.

Analysis:

10,405 paths (most are nested navigation bloat)

4,292 schemas (3,242 unused - 75%)

1,157 responses (521 unused - 45%)

2,360 examples (all unused)

Impact:

Clients freeze/crash loading the spec

Impossible to explore the API effectively

Poor developer experience

Proposed Remedies:

Option 1: Limit navigation depth (Recommended)
Configure Microsoft.OpenApi.OData to only generate direct resource operations, not nested navigation paths. Max depth of 1 would reduce 10K paths to ~500-1000 useful endpoints.

Option 2: Split by service area
Publish separate specs per service:

openapi-files.yaml - drives/items/sites (core file operations only)

openapi-users.yaml - users/groups

openapi-mail.yaml - messages/mailFolders

openapi-calendar.yaml - events/calendars

etc.

Option 3: Provide filtered variants

openapi-full.yaml - complete with all navigation (current)

openapi-core.yaml - direct operations only, no nested navigation

openapi-{service}.yaml - per-service splits

Option 4: Post-generation pruning
Add a build step that removes:

Navigation paths beyond depth 1

Unused schemas/responses

All examples (2,360 unused)

Proof of Concept:
Filtering to just essential file operations (21 paths) reduces the spec from 35MB to 1.1MB - a 97% reduction while maintaining full functionality.