Read group documentation from document tags.

[DJ4ddi]

The controller XML documentation generated by Refitter currently uses the first operation within that controller to set the summary. This is unintuitive and often unnecessary as tools like Swashbuckle and NSwag are able to extract controller documentation, which is stored in the description of the associated tag.

This pull requests slightly modifiers the documentation generation. It attempts to find a controller tag with a description. If the relevant information is not found, no documentation is generated to avoid writing incorrect or pointless information.

I did not introduce a configuration option for this because I can't imagine anyone preferring the old behavior.

Summary by CodeRabbit

• New Features

  • Interface documentation now prefers controller tag descriptions for summaries, falls back to endpoint- or document-level summaries, and consistently escapes symbols and preserves multi-line content.
  • Group names are normalized more consistently for generated interfaces.

• Tests

  • Added a test verifying interface documentation can be generated from controller tag descriptions when available.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[coderabbitai]

📝 Walkthrough

Walkthrough

Interface documentation generation was split into three entry points (by tag, by endpoint, by document title). Refit generators were updated to call the appropriate new methods and tests were added to verify tag-derived interface summaries.

Changes

Cohort / File(s)	Summary
Tag-based interface generator src/Refitter.Core/RefitMultipleInterfaceByTagGenerator.cs	Replaced per-tag interface doc call with AppendInterfaceDocumentationByTag(document, tag, sb) so tag + document context is passed when building interfaces.
Endpoint-multiple interface generator src/Refitter.Core/RefitMultipleInterfaceGenerator.cs	Replaced operation-level doc call with AppendInterfaceDocumentationByEndpoint(operation, sb); only the documentation call site changed.
Single interface generator src/Refitter.Core/RefitInterfaceGenerator.cs	Now calls AppendSingleInterfaceDocumentation(document, sb) for single-interface declarations.
Documentation implementation src/Refitter.Core/XmlDocumentationGenerator.cs	Added AppendInterfaceDocumentationByTag(OpenApiDocument,string,StringBuilder), AppendInterfaceDocumentationByEndpoint(OpenApiOperation,StringBuilder), AppendSingleInterfaceDocumentation(OpenApiDocument,StringBuilder) and SummaryTag constant; replaced literal "summary" usage and ensured symbol escaping.
Identifier utilities src/Refitter.Core/IdentifierUtils.cs	Added SanitizeControllerTag(this string) extension to sanitize and capitalize tag names used for group naming.
Tests src/Refitter.Tests/XmlDocumentationGeneratorTests.cs	Updated endpoint-level test calls and added Can_Generate_Interface_Doc_From_Controller_Tag() to assert controller-tag-derived summaries.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related PRs

• Ensure that Refit interfaces have a <summary> #709: Modifies XmlDocumentationGenerator and generator call sites to change interface-level documentation APIs — strong code-level overlap.

Suggested labels

.NET

Poem

🐰 I hop through tags and nibble on a line,

Controller notes become the docs I sign.
Endpoints sing, document titles chime,
I stitch their summaries, one little rhyme.
Hooray — interface docs, neat and fine!

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 46.67% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'Read group documentation from document tags' accurately reflects the main objective of the PR, which is to change how controller/group documentation is sourced from OpenAPI document tags instead of the first operation.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing touches

• 📝 Generate docstrings

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[codecov]

Codecov Report

❌ Patch coverage is 94.44444% with 1 line in your changes missing coverage. Please review.
✅ Project coverage is 93.33%. Comparing base (44d46fe) to head (5c2e184).
⚠️ Report is 11 commits behind head on main.

Files with missing lines	Patch %	Lines
src/Refitter.Core/XmlDocumentationGenerator.cs	92.85%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #887      +/-   ##
==========================================
+ Coverage   93.30%   93.33%   +0.02%     
==========================================
  Files          23       23              
  Lines        1389     1395       +6     
==========================================
+ Hits         1296     1302       +6     
- Misses         46       47       +1     
+ Partials       47       46       -1     

Flag	Coverage Δ
unittests	93.33% <94.44%> (+0.02%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[coderabbitai]

Actionable comments posted: 2

🤖 Fix all issues with AI agents

In `@src/Refitter.Core/XmlDocumentationGenerator.cs`:
- Around line 45-50: The code risks a NullReferenceException when accessing
document.Tags or group.Tags; update the lookup that creates controllerTag in
XmlDocumentationGenerator (where controllerTag, document.Tags, group.Tags, and
group.Summary are used) to use null-conditional checks: ensure you only call
.FirstOrDefault when document.Tags is not null and use group.Tags?.Contains(...)
or guard when group.Tags is null, and then safely fall back to group.Summary (or
group.Summary ?? string.Empty) so the code never dereferences a null Tags
collection.
- Around line 46-52: The summary text (computed from controllerTag?.Description
or group.Summary) must be XML-escaped before emitting to AppendXmlCommentBlock
to avoid invalid XML when the text includes '<', '>' or '&'; modify
XmlDocumentationGenerator.cs so that after computing content (the variable used
in the call to AppendXmlCommentBlock) you pass it through an XML-escape function
(e.g., System.Security.SecurityElement.Escape or another XML-encoding helper)
and then call AppendXmlCommentBlock("summary", escapedContent ?? "No summary
available", code, indent: Separator).

🧹 Nitpick comments (1)

src/Refitter.Core/XmlDocumentationGenerator.cs (1)

31-38: Consider keeping the previous overload for backward compatibility.

This signature change is a breaking public API change for downstream consumers. Consider adding the old overload (or marking it [Obsolete]) that preserves the previous behavior when a document isn’t available.

[christianhelle]

@DJ4ddi thanks for taking the time to implement this.

I'm looking into this now

[DJ4ddi]

I'm realizing this behavior also applies to generating multiple interfaces by endpoint, in which case it may not produce the best result. It might make sense to restrict the new behavior to the RefitMultipleInterfaceByTagGenerator implementation.

[christianhelle]

@DJ4ddi The changes look good but its lacking support for generating multiple interfaces by endpoint. Do you mind implementing that?

[christianhelle]

I'm realizing this behavior also applies to generating multiple interfaces by endpoint, in which case it may not produce the best result. It might make sense to restrict the new behavior to the RefitMultipleInterfaceByTagGenerator implementation.

@DJ4ddi Sorry, I was deep in reviewing when you wrote this. We noticed the same thing 😄

[coderabbitai]

Actionable comments posted: 0

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

src/Refitter.Core/RefitMultipleInterfaceByTagGenerator.cs (1)

48-53: ⚠️ Potential issue | 🟠 Major

Use raw tag names for lookup and preserve fallback when no tag description exists.

kv.Key is sanitized for identifier purposes, so AppendInterfaceDocumentationByTag(document, kv.Key, ...) can miss matching document.Tags entries (e.g., spaces/hyphens). Also, when no tag description exists, the summary now disappears; per the PR objective, it should fall back to the first operation summary. A small guard based on StringBuilder length preserves that behavior.

🔧 Suggested fix (raw tag + fallback to endpoint summary)

-                    interfacesByGroup[kv.Key] = sb = new StringBuilder();
-                    this.docGenerator.AppendInterfaceDocumentationByTag(document, kv.Key, sb);
+                    interfacesByGroup[kv.Key] = sb = new StringBuilder();
+
+                    var rawTag = operation.Tags.FirstOrDefault();
+                    var tagForDocs = !string.IsNullOrWhiteSpace(rawTag) ? rawTag : kv.Key;
+                    var initialLength = sb.Length;
+                    this.docGenerator.AppendInterfaceDocumentationByTag(document, tagForDocs, sb);
+                    if (sb.Length == initialLength)
+                    {
+                        this.docGenerator.AppendInterfaceDocumentationByEndpoint(operation, sb);
+                    }

Based on learnings: In the Refitter codebase using NSwag, the OpenApiDocument.Tags and OpenApiOperation.Tags collections are not nullable and will be empty collections when the model has no tags, so null-conditional checks are not required.

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

[Copilot]

Pull request overview

This pull request improves the XML documentation generation for Refit interfaces by using OpenAPI controller tag descriptions instead of the first operation's summary. The change makes generated documentation more accurate and intuitive, aligning with how tools like Swashbuckle and NSwag handle controller documentation.

Changes:

• Interface documentation now uses controller tag descriptions when available, with graceful fallback to endpoint or document-level summaries
• Refactored documentation methods with clearer names to distinguish between tag-based, endpoint-based, and document-based documentation generation
• Added consistent symbol escaping and eliminated generic placeholder documentation when meaningful descriptions are unavailable

Reviewed changes

Copilot reviewed 6 out of 10 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
src/Refitter.Core/XmlDocumentationGenerator.cs	Added new AppendInterfaceDocumentationByTag method, renamed existing methods for clarity, added consistent XML symbol escaping, and eliminated meaningless placeholder documentation
src/Refitter.Core/IdentifierUtils.cs	Added SanitizeControllerTag helper method to centralize tag sanitization logic
src/Refitter.Core/RefitMultipleInterfaceByTagGenerator.cs	Updated to use new tag-based documentation method and centralized sanitization
src/Refitter.Core/RefitMultipleInterfaceGenerator.cs	Updated to use renamed endpoint-based documentation method
src/Refitter.Core/RefitInterfaceGenerator.cs	Updated to use renamed single-interface documentation method
src/Refitter.Tests/XmlDocumentationGeneratorTests.cs	Added test for tag-based documentation and updated existing tests to use renamed methods
src/Refitter.SourceGenerator.Tests/AdditionalFiles/Generated/*.g.cs	Updated snapshot files showing improved documentation from tag descriptions and removal of uninformative generic summaries

[Copilot]

Consider adding test cases for edge scenarios such as: tags with null or empty descriptions, tags that don't exist in the document, and tag descriptions containing XML special characters (e.g., "<", ">", "&") to verify the EscapeSymbols functionality works correctly in this context.

[christianhelle]

@DJ4ddi this looks much better. Let's get this in.

I'll consider the AI suggestions at a later point