Exhaustive OData Navigation Path Generation Problem

Offen
#1,000 1 Kommentar 0 Reaktionen 0 zugewiesene Personen Auf GitHub ansehen

Maintainer antworten meist innerhalb von 2 Tagen

Dieses Issue hat noch niemand übernommen.

Bewertung

Schwierigkeit
5/5
Geschätzter Aufwand
Über eine Woche
Anfängerfreundlichkeit
35/100
Issue-Typ
Feature
Klarheit
Größtenteils klar
Aktivitätsstatus
Veraltet
Tech-Stack
openapi

Rechercherichtung

Es werden keine Quelldateien, Tests oder Einstiegspunkte genannt. Beginne damit, den Generierungsablauf von Microsoft.OpenApi.OData zu lokalisieren und die 35MB-Spezifikation v1.0 zu reproduzieren; vergleiche anschließend eine tiefenbegrenzte oder gefilterte Ausgabe mit dem Proof of Concept mit 21 Pfaden. Als abgeschlossen sollte eine praktische Reduzierung der Pfade und der Spezifikationsgröße gelten, ohne die erforderlichen direkten Operationen zu verlieren.

Vom Indexierungsmodell aus dem Issue-Text verfasst.

Beschreibung

ToTriage

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.

Vorherrschende Sprache
XSLT
Sterne
171
Forks
56
Ø Merge
1 T. 11 Std.
Gemergte PRs (30 T.)
9

Entwicklungsumgebung

Dieses Projekt bietet weder Dev-Container noch Dockerfile noch Beitragsleitfaden – die Einrichtung liegt bei Ihnen. Beginnen Sie mit der README; die allgemeinen Schritte stehen in unserem Leitfaden für den ersten Beitrag.

Erste Schritte

  1. Lesen Sie das ganze Issue und danach den Beitragsleitfaden des Projekts.
  2. Schreiben Sie ins Issue, dass Sie es übernehmen — das erspart doppelte Arbeit.
  3. Forken Sie das Repository und arbeiten Sie in einem Branch.
  4. Öffnen Sie einen Pull Request, der die Issue-Nummer nennt.

Mehr aus microsoftgraph/msgraph-metadata

Alle Issues in microsoftgraph/msgraph-metadata

Ähnliche Issues

Weitere Issues zu Backend & API Design

Neue Issues direkt in Ihr Postfach

Eine kurze Übersicht über anfängerfreundliche GitHub-Issues.