RicoSuter / NJsonSchema

JSON Schema reader, generator and validator for .NET
http://NJsonSchema.org
MIT License
1.38k stars 532 forks source link

[type: enhancement] On C# client generation: Convert description fields to XML comment syntax #1626

Open jeremia opened 12 months ago

jeremia commented 12 months ago

Description fields in Swagger can be in markdown or html. There are multiple cases where a markdown syntax och html syntax have a corresponding xml comment syntax. It would be nice if the generated XML comment (for summary, remarks, param and returns) would be converted to XML comment syntax.

This is related to #1171 and #1364.

XML Comments syntax: https://learn.microsoft.com/en-us/dotnet/csharp/language-reference/xmldoc/recommended-tags Markdown syntax: https://www.markdownguide.org/cheat-sheet/

Examples

Description Markdown example HTML example XML Comment
Code `asdf` | N/A | <c>asdf</c>
Code block ```
Console.WriteLine("asdf");
``` | N/A | <code lang="csharp">
Console.WriteLine("asdf");
</code>
Unordered list * a
* b
* c
OR
- a
- b
- c
<ul>
<li>a</li>
<li>b</li>
<li>c</li>
</ul>
<list type="bullet">
<item>a</item>
<item>b</item>
<item>c</item>
</list>
Ordered list 1. a
2. b
3. c
<ol>
<li>a</li>
<li>b</li>
<li>c</li>
</ol>
<list type="number">
<item>a</item>
<item>b</item>
<item>c</item>
</list>
Table \| Heading 1 \| Heading 2 \|
\| -- \| -- \|
\| row1Value1 \| row1Value2 \|
<table>
<tr>
  <th>Heading 1</th>
  <th>Heading 2</th>
<tr>
  <td>row1Value1</td>
  <td>row1Value2</td>
</tr>
</table>
<list type="table">
<listheader>
  <term>Heading 1</term>
  <term>Heading 2</term>
</listheader>
<item>
  <term>row1Value1</term>
  <term>row1Value2</term>
</item>
</list>