Skill v1.0.1

version: "1.0.1" name: "xml-doc-description-sanitization" description: "Preserve readable Unicode when copying OpenAPI response descriptions into XML doc comments" domain: "code-generation" confidence: "high" source: "manual"

Context

src\Refitter.Core\XmlDocumentationGenerator.cs writes OpenAPI response descriptions into generated XML documentation comments. Those descriptions may arrive from NSwag in JSON-escaped form (\uXXXX, \", \n) even though the source OpenAPI file already contains readable Unicode.

Pattern

Sanitize user-sourced response descriptions only

• Decode JSON-style escape sequences before writing the text into XML docs.
• After decoding, escape XML-reserved characters (&, <, >) so the generated comments remain valid XML.
• Apply this only to OpenAPI-sourced response description text such as method.ResultDescription and response.ExceptionDescription.

Preserve intentional XML doc markup

• Do not run the same sanitization over hardcoded fallback strings that intentionally contain <see cref="..."/>, <list>, or other XML doc tags.
• Sanitize at the insertion point where raw API text enters the XML comment output.

Example

var description = this.EscapeSymbols(this.DecodeJsonEscapedText(responseDescription));

Anti-Patterns

• Appending method.ResultDescription or response.ExceptionDescription directly into XML comments.
• XML-escaping entire doc fragments that intentionally contain XML doc markup.