Fix non-idempotent model class descriptions for shared component schemas (#7927)

[Gavin Barron (gavinbarron)]

Fixes #7927

Problem

When an OpenAPI component schema is referenced directly as the type of multiple properties, and those $ref sites carry different sibling descriptions, Kiota could emit a different class-level description on each run (idempotency failure). Reproduced with notion.com, where the component internalFileResponse is $ref'd from several properties, each $ref adding its own description (e.g. "The file URL for the cover.", "The file URL for the icon.").

Root cause

KiotaBuilder.AddModelClass sourced the class DescriptionTemplate from schema.Description. For an OpenApiSchemaReference, .Description returns the reference object's own (sibling) description first, falling back to the target only when absent. Since models are built by parallel tasks and the same class can be reached from several $ref sites, which sibling description "wins" was non-deterministic.

Fix

Derive the class description from the schema definition/target (via a new GetModelClassDescription helper): use schemaRef.Target for references, otherwise the schema itself, then apply the existing own-description → non-referenced allOf fallback. This makes the class description identical regardless of which reference triggers creation. The reference-level (property) description path in CreateProperty is unchanged and still describes the property.

This matches the behavior defined by Vincent Biret (@baywet) in the issue:

• Both schema and reference descriptions present → schema description for the class, reference description for the property.
• Only schema description → used for both class and property.
• Only reference-level description → property only; class description left empty.
• allOf crawl retained as a fallback.

Tests

Added two regression tests in KiotaBuilderTests.cs covering the shared-component scenario with differing $ref descriptions, with and without a target description. Verified they fail against the pre-fix code and pass after. Full KiotaBuilderTests (336) and the description/inheritance/allOf suites (164) pass with no new warnings.

[github-code-quality]

Code Coverage Overview

Languages: C#

C# / code-coverage/dotnet

The overall coverage in commit 1de07a8 in the gavinbarron/fix-7927... branch is 72%. Coverage data for the main branch is not yet available.

Show a code coverage summary of the most covered files.

File	main	gavinbarron/fix-7927... 1de07a8	+/-
/home/runner/wo...guageRefiner.cs	—	98%	—
/home/runner/wo...criptRefiner.cs	—	98%	—
/home/runner/wo...MethodWriter.cs	—	97%	—
/home/runner/wo...MethodWriter.cs	—	96%	—
/home/runner/wo...MethodWriter.cs	—	96%	—
/home/runner/wo...MethodWriter.cs	—	95%	—
/home/runner/wo...rs/GoRefiner.cs	—	94%	—
/home/runner/wo...KiotaBuilder.cs	—	90%	—
/home/runner/wo...ationService.cs	—	89%	—
/home/runner/wo...xGenerator.g.cs	—	75%	—

---

_{Updated July 20, 2026 15:58 UTC}

[Vincent Biret (baywet)]

Thanks for the contribution!