如何在 Swashbuckle 文档中添加换行符？答案

【问题标题】：How to add line break to Swashbuckle documentation?如何在 Swashbuckle 文档中添加换行符？
【发布时间】：2015-09-14 07:10:23
【问题描述】：

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

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

有什么办法吗？

【问题讨论】：

【解决方案1】：

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

/// <br />

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

【讨论】：

在 VS 2017 和 SwashBuckle.AspNetCore 2.4 中它不起作用 - 字面意思是  
@MichaelFreidgeim：对我来说，这适用于带有 SwashBuckle.AspNetCore 2.4 的 VS2017 Preview 2.0。但是：如果您将   放在某些文本的末尾（而不是单独一行），那么您可能不会在该 text  行之后添加空行！换句话说：任何text  之后的行中必须有文本，否则将忽略换行符。我花了一段时间才找到那个小细节。

【解决方案2】：

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

希望对你有帮助

山姆

【讨论】：

【解决方案3】：

使用 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>

【讨论】：

【解决方案4】：

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

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

【讨论】：

【解决方案5】：

在 SwashBuckle.AspNetCore   和 &lt;br /&gt(suggested in github) 中不起作用。在<remarks> 中，您可以在行尾指定反斜杠。

例如

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

生成 2 行

before.
after.

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

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

【讨论】：

【解决方案6】：

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

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

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

【讨论】：

【解决方案7】：

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

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

【讨论】：

【解决方案8】：

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

【讨论】：

【解决方案9】：

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

示例：

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

【讨论】：