Repository navigation
Fix #3240: keep a property's own summary when comments come from several XML files - #4129
Conversation
… come from several XML files Each IncludeXmlComments call registers its own XmlCommentsSchemaFilter, and every one of them wrote the type's summary into the schema unconditionally. For a member's schema the filter for the assembly that knows the property set the property summary, and the filter for the assembly that only knows the class then overwrote it with the class summary, so the description depended on XML load order. For a member's schema the type summary is now a fallback: it applies only when nothing has described the member yet. Definition schemas and the single file case are unchanged.
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## master #4129 +/- ##
=======================================
Coverage 95.21% 95.21%
=======================================
Files 111 111
Lines 4115 4118 +3
Branches 843 844 +1
=======================================
+ Hits 3918 3921 +3
Misses 197 197
Flags with carried forward coverage won't be shown. Click here to find out more. ☔ View full report in Codecov by Harness. 🚀 New features to boost your workflow:
|
There was a problem hiding this comment.
🟢 Approval recommended
The focused implementation preserves existing definition behavior and includes adequate regression coverage.
Pull request overview
Fixes XML comment precedence so property summaries survive when multiple XML files are loaded.
Changes:
- Treats type summaries as fallbacks for member schemas.
- Adds regression and fallback tests for multiple XML documents.
File summaries
| File | Description |
|---|---|
XmlCommentsSchemaFilter.cs |
Prevents type summaries from overwriting existing member descriptions. |
XmlCommentsSchemaFilterTests.cs |
Tests summary precedence and fallback behavior. |
Review details
- Files reviewed: 2/2 changed files
- Comments generated: 0
- Review effort level: Balanced
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
|
Thanks for your contribution @RaphaelFakhri - the changes from this pull request have been published as part of version 10.3.0 📦, which is now available from NuGet.org 🚀 |
Fixes #3240.
The long thread here settles into two different problems. The original single-assembly complaint, a property's summary being discarded on a
$refproperty, is the OpenAPI 3.0 limitation with the documented opt-in remedy,UseAllOfToExtendReferenceSchemas(), and that part is working as intended. What remains is the multiple-XML-file case further down the thread, where the description you get depends on which XML file was loaded last.That part is fixable. Each
IncludeXmlComments()call registers its ownXmlCommentsSchemaFilter, andApplyTypeTagswrote the type's<summary>intoschema.Descriptionunconditionally. For a member's schema that means the filter for the assembly that knows the property sets the property summary, and then the filter for the assembly that only knows the class overwrites it with the class summary. Reverse the order of the twoIncludeXmlCommentscalls and the output changes.For a member's schema the type summary is now treated as a fallback and applies only when nothing has described the member yet:
Definition schemas, where
MemberInfois null, are unchanged. The single-file case is unchanged too, since member tags are applied after type tags within one filter and still take precedence.Two tests in
XmlCommentsSchemaFilterTests: one reproduces the two-file clobber, and one guards that the type summary still applies as a fallback when the property has no summary of its own. Reverting the source change makes the first fail with the class summary as the actual value. With the change,Swashbuckle.AspNetCore.SwaggerGen.Testis 762 passed, 0 failed on net8.0.Two observable changes worth stating rather than leaving to be found. For a member's schema, the type summary no longer overwrites a description that something else has already set, which includes a schema filter a user registered before
IncludeXmlComments. And when two XML files both carry the same type's summary, the first loaded now wins as the fallback rather than the last. Both look like corrections rather than regressions to me, but they are behaviour changes and worth your call.