asp.net-web-api - 如何在 Swashbuckle 文档中添加换行符？

Question

我正在为使用 swagger/swashbuckle 在 Web Api 2 中实现的 api 生成文档。

唯一可识别的 xml 文档标签是<summary>,<remarks>和<param>.
这意味着我不能使用<para>标签在新的行或段落中格式化我的文本，所有内容都在文档的实施说明条目中生成为连续的长段落。

有没有办法做到这一点？

score 22 · Accepted Answer

我发现你可以 在评论中添加标签来实现这一点。
添加：

/// <br />

将导致生成的文档中出现换行符。

score 7 · Accepted Answer

另一种实现方法是创建自定义 OperationFilter 并使用 xml 文档标签，如下所述：

希望这可以帮助

山姆

score 4 · Accepted Answer

使用 Visual Studio 2019 (.net core 3.1)，我可以使用 html 注释。它可以在一条线上使用 . 我还尝试了其他 html 标签，例如下划线和粗体。

/// <summary>
    /// test
    /// </summary>
    /// <remarks><u>underline</u> "test line 1" <br /><b>Bold</b> "test line 2"  </remarks>

score 3 · Accepted Answer

在 SwashBuckle.AspNetCore 和 您可以在行尾指定反斜杠。

例如

/// <remarks>
///  before. \
///  after.  
/// </remarks>

生成 2 行

before.
after.

但是我无法在<summary>部分中生成多行。

请注意，如果该行有尾随空格（例如"before. \ "），则反斜杠将按字面意思显示在输出中。您可以在https://github.com/MNF/Samples/blob/master/SwashbuckleExample/SwashbuckleExample/Controllers/SwashBuckleTest.cs中看到我的一些尝试

score 3 · Accepted Answer

所有已发布的解决方案均不适用于新版本的 Swagger。如果要在注释行之间使用换行符分隔，则必须添加///换行符。这使得方法注释很长，但在 Swagger 文档中它们将更具可读性。

///  <summary>
/// Comment Line 1
///  
/// Comment Line 2
///  
/// Comment Line 3
///  </summary>

score 2 · Accepted Answer

使用下面的结构，Swashbuckle UI 和 ReDoc UI 都可以工作：

/// <summary> 
/// Title
/// 
/// <para>Content line 1</para> 
/// <para>Content line 2</para> 
/// <para>Content line 3/</para> 
/// </summary>

重要提示：不要忽略每行末尾的空格

score 2 · Accepted Answer

如果没有一个答案对你有用，那么在某些情况下部分工作就像我一样。

您可以使用 . 不要使用. 它有时会破坏 XML。Visual Studio 显示错误的 XML 格式 

score 1 · Accepted Answer

根据markdown规范，可以在备注中添加一个新行，方法是添加一个双空格（两个空格）来结束行

score 0 · Accepted Answer

经过长时间的搜索，我发现 *** 是粗体文本，我知道这不是同一个主题，但我很确定这对这里的人有用！

例子：

***400 - BadRequest When any parameter is out of specification.***

9 回答 9