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

Question

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

唯一可识别的 xml 文档标签是

<summary>

、

<remarks>

和

<param>

。
这意味着我无法使用

<para>

标签来格式化新行或段落中的文本，所有内容都在文档的实施说明条目中生成为连续的长段落。

有什么办法可以做到这一点吗？

Answer 1

我发现你只需在评论中添加

<br />

标签即可实现此目的。
添加：

/// <br /> 

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

Answer 2

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

https://github.com/domaindrivendev/Swashbuckle/issues/258

希望这有帮助

山姆

Answer 3

在 SwashBuckle.AspNetCore 中

<br />

和

<br /&gt

（在 github 中建议）不起作用。 在

<remarks>

中，您可以在行尾指定反斜杠。

例如

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

生成2行

before.
after.

但是我无法在

<summary>

部分生成多行。

注意，如果该行有尾随空格（例如

"before. \  "

），反斜杠将在输出中按字面显示。 您可以在https://github.com/MNF/Samples/blob/master/SwashbuckleExample/SwashbuckleExample/Controllers/SwashBuckleTest.cs

中看到我的一些尝试

Answer 4

发布的解决方案均不适用于较新版本的 Swagger。如果您希望注释行之间有换行符分隔，则必须为换行符添加

///

。这使得方法注释变得冗长，但在 Swagger 文档中它们将更具可读性。

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

Answer 5

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

Answer 6

使用Visual Studio 2019（.net core 3.1），我可以使用html注释。 使用

<br />

可以在一行内完成所有操作。 我还尝试过其他 html 标签，例如下划线和粗体。

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

Answer 7

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

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

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

Answer 8

如果所有答案都不适合您，则在某些情况下部分有效，就像我一样。

您可以使用

<br></br>

。不要使用

</br>

。有时它会破坏 XML。 Visual Studio 显示

<br/>

的 XML 格式错误

Answer 9

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

示例：

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

Answer 10

我使用 Visual Studio 2022 和 openapi 版本 3.0.1 作为默认值， 要完整的文档，你可以这样做，
首先：确保您在项目中启用了 XML 文档，如下所示：

1. 编辑您的 .csproj 文件（我的项目是 .net core 7，您也可以对 core 8 执行此操作）：
   

<PropertyGroup>
    <TargetFramework>net7.0</TargetFramework>
    <GenerateDocumentationFile>true</GenerateDocumentationFile>
    <DocumentationFile>bin\Debug\net7.0\WebApi.xml</DocumentationFile>
    <NoWarn>$(NoWarn);1591</NoWarn>
</PropertyGroup>

这将在路径 bin\Debug 处创建 WebApi.xml 文件 et7.0\ 每当您构建项目时。
注意： 如果所有方法都没有 XML 注释，NoWarn 会抑制警告。

现在您可以为自定义文档添加多行和示例，如下所示：

/// <summary>
/// Latest Version: 1.0.2
/// </summary>
/// <remarks>
/// ### Version Walkthrough:
///
/// #### Version 1.0.0 (Base Version):
///
/// ```json
/// {
///   "version": "string",  // Optional, 1.0.0 is Default
///   "defParam1": 0,       // Mandatory
///   "defParam2": "string" // Mandatory
/// }
/// ```
///
/// #### Version 1.0.1:
///
/// ```json
/// {
///   "newParam1": "string",  // Added in ver1.0.1 for specific feature
///   "newParam2": "string"   // Added in ver1.0.1 for another feature
/// }
/// ```
///
/// #### Version 1.0.2:
///
/// ```json
/// {
///   "newParam3": "string"  // Added in ver1.0.2 for new functionality
/// }
/// ```
///
/// ### Example Request:
///
/// ```json
/// {
///   "version": "1.0.2",
///   "defParam1": 123,
///   "defParam2": "sample data",
///   "newParam3": "new data"
/// }
/// ```
/// </remarks>
/// <response code="201">Returns the newly created item</response>
/// <response code="400">If the item is null</response>
/// <response code="401">Authorization is failed</response>
[HttpPost]
public ProcedureVersioningViewModel GetAllProcedureVersion(GetProcedureVerionResponseItemViewModel model)
{
    return _procedureVersionService.GetAllProcedureVersion(model);
}

输出是这样的（我如何向 swagger 添加一些 CSS 和样式以使其 UI 更漂亮）：