From 45a2cb71996868e71dc5cad9aef6f5e7cac533ba Mon Sep 17 00:00:00 2001
From: Maxwell Weru <mburumaxwell@gmail.com>
Date: Mon, 15 Apr 2024 17:27:21 +0300
Subject: [PATCH] Use Markdown link format for see href tags (#2392)

Resolves #2577.
---
 .../XmlComments/XmlCommentsTextHelper.cs                   | 7 +++++++
 .../XmlComments/XmlCommentsTextHelperTests.cs              | 1 +
 2 files changed, 8 insertions(+)

diff --git a/src/Swashbuckle.AspNetCore.SwaggerGen/XmlComments/XmlCommentsTextHelper.cs b/src/Swashbuckle.AspNetCore.SwaggerGen/XmlComments/XmlCommentsTextHelper.cs
index 1d8f8c3825..5781d4d2e9 100644
--- a/src/Swashbuckle.AspNetCore.SwaggerGen/XmlComments/XmlCommentsTextHelper.cs
+++ b/src/Swashbuckle.AspNetCore.SwaggerGen/XmlComments/XmlCommentsTextHelper.cs
@@ -11,6 +11,7 @@ public static class XmlCommentsTextHelper
         private static Regex CodeTagPattern = new Regex(@"<c>(?<display>.+?)</c>");
         private static Regex MultilineCodeTagPattern = new Regex(@"<code>(?<display>.+?)</code>", RegexOptions.Singleline);
         private static Regex ParaTagPattern = new Regex(@"<para>(?<display>.+?)</para>", RegexOptions.Singleline);
+        private static Regex HrefPattern = new(@"<see href=\""(.*)\"">(.*)<\/see>");
 
         public static string Humanize(string text)
         {
@@ -22,6 +23,7 @@ public static string Humanize(string text)
             return text
                 .NormalizeIndentation()
                 .HumanizeRefTags()
+                .HumanizeHrefTags()
                 .HumanizeCodeTags()
                 .HumanizeMultilineCodeTags()
                 .HumanizeParaTags()
@@ -92,6 +94,11 @@ private static string HumanizeRefTags(this string text)
             return RefTagPattern.Replace(text, (match) => match.Groups["display"].Value);
         }
 
+        private static string HumanizeHrefTags(this string text)
+        {
+            return HrefPattern.Replace(text, m => $"[{m.Groups[2].Value}]({m.Groups[1].Value})");
+        }
+
         private static string HumanizeCodeTags(this string text)
         {
             return CodeTagPattern.Replace(text, (match) => "`" + match.Groups["display"].Value + "`");
diff --git a/test/Swashbuckle.AspNetCore.SwaggerGen.Test/XmlComments/XmlCommentsTextHelperTests.cs b/test/Swashbuckle.AspNetCore.SwaggerGen.Test/XmlComments/XmlCommentsTextHelperTests.cs
index cc6d8090a0..7690cd78fd 100644
--- a/test/Swashbuckle.AspNetCore.SwaggerGen.Test/XmlComments/XmlCommentsTextHelperTests.cs
+++ b/test/Swashbuckle.AspNetCore.SwaggerGen.Test/XmlComments/XmlCommentsTextHelperTests.cs
@@ -131,6 +131,7 @@ Misplaced Tab Indentation
         [InlineData("<para>This is a paragraph</para>.", "<br>This is a paragraph.")]
         [InlineData("GET /Todo?iscomplete=true&amp;owner=mike", "GET /Todo?iscomplete=true&owner=mike")]
         [InlineData(@"Returns a <see langword=""null""/> item.", "Returns a null item.")]
+        [InlineData(@"<see href=""https://www.iso.org/iso-4217-currency-codes.html"">ISO currency code</see>", "[ISO currency code](https://www.iso.org/iso-4217-currency-codes.html)")]
         public void Humanize_HumanizesInlineTags(
             string input,
             string expectedOutput)