How to add line break to Swashbuckle documentation?

Question

I'm generating documentation for an api implemented in Web Api 2 using swagger/swashbuckle.

The only xml documentation tags recognized are the <summary>, <remarks> and <param>.
This means I cannot use <para> tag to format my text in new lines or paragraphs, everything is generated as a continuous long paragraph in the Implementation Notes entry of the docs.

Is there any way to do this?

score 23 · Answer 1 · answered Sep 14 '15 at 08:17

23

I found that you can just add   tags to the comments to achieve this.
Adding:

/// <br />

will cause a line break in the generated documentation.

answered Sep 14 '15 at 08:17

Attila Szasz

3,033
3
25
39

In VS 2017 and SwashBuckle.AspNetCore 2.4 it doesn't work- shows literally `
` – Michael Freidgeim Apr 11 '18 at 01:31
@MichaelFreidgeim: For me this works in VS2017 Preview 2.0 with SwashBuckle.AspNetCore 2.4. BUT: If you place the `
` at the end of some text (instead of in a line of its own) then you may NOT add an empty line after that `text
` line! In other words: there MUST be text in the line following any `text
` or the line break will be ignored. Took me while to find that little detail. – Jpsy Jun 18 '18 at 08:39

score 8 · Accepted Answer · answered Sep 22 '15 at 14:09

8

Another way to achieve is creating a custom OperationFilter and use the xml documentation tags as explained in :

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

Hope this helps

Sam

answered Sep 22 '15 at 14:09

Sam Sole

96
3

Setting this as the accepted answer, it's the more elegant solution. – Attila Szasz Sep 22 '15 at 16:03
Adding the description inside tag worked for me – Chris Sim Dec 19 '18 at 11:42

Michael Freidgeim · Answer 3 · 2020-02-26T04:07:14.780

In SwashBuckle.AspNetCore   and   you can specify backslash at the end of line.

For example

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

generates 2 lines

before.
after.

However I was NOT able to generate multiple lines in <summary> section.

Note, If the line has trailing spaces(e.g. "before. \ "), backslash will be shown literally in the output. You can see a few my attempts in https://github.com/MNF/Samples/blob/master/SwashbuckleExample/SwashbuckleExample/Controllers/SwashBuckleTest.cs

nPcomp · Answer 4 · 2018-11-16T21:36:13.467

4

None of the posted solutions will work with the newer version of Swagger. If you want a newline separation between your comment lines, you have to add /// for newline. That makes method comments lengthy but they will be more readable in the Swagger documentation.

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

edited Nov 16 '18 at 21:36

answered Nov 16 '18 at 20:17

nPcomp

8,637
2
54
49

Adding /// extra line works for me. but this is no ideal solution, I am using NSwag.AspNet.Core – Gautam Sharma Feb 04 '21 at 14:53

score 4 · Answer 5 · answered Apr 26 '20 at 13:49

Using Visual Studio 2019 (.net core 3.1), I'm able to use html remarks. It can be done all on one line using  . I've also tried other html tags such as underline and bold.

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

score 4 · Answer 6 · answered May 30 '21 at 22:17

4

As per markdown specification, a new line can be added in remarks by adding a double space (two spaces) to end the line

answered May 30 '21 at 22:17

Michael Smale

583
9
15

score 2 · Answer 7 · edited May 29 '19 at 18:36

2

Using the structure below, both the Swashbuckle UI and the ReDoc UI will work:

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

Important note: Do not ignore the spaces at the end of each line

edited May 29 '19 at 18:36

Nazim Kerimbekov

4,712
8
34
58

answered May 29 '19 at 11:20

Silvair L. Soares

1,018
12
28

score 2 · Answer 8 · answered Jun 19 '19 at 09:59

2

If none of the answers worked for you, worked partially in some case like it was with me.

You can use  . Do not use . It can break XML sometimes. Visual studio showed bad XML formatting for  

answered Jun 19 '19 at 09:59

Ameya

726
6
9

score 0 · Answer 9 · answered Aug 20 '20 at 14:33

0

after a long search i found that *** is for Bold text , i know it s not the same subject but i am pretty sure that will be useful for someone here !

example :

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

answered Aug 20 '20 at 14:33

Abdessamad Jadid

381
1
4
16

How to add line break to Swashbuckle documentation?

9 Answers9

Linked