CODEWITHSUNDEEP
asp.net-web-apiswaggerswagger-uiline-breaksswashbuckle
Attila Szasz
Attila Szasz

Reputation: 3073

How to add line break to Swashbuckle documentation?

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?

Upvotes: 18

Views: 23057

Answers (10)

Reza Paidar
Reza Paidar

Reputation: 883

I am using Visual Studio 2022 and openapi version 3.0.1 as its default, To full documentation, you can do like this,
First: make sure you enabled XML Documentation in the Project like this:

  1. Edit your .csproj file (my project is .net core 7 you can also do this for core 8):

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

This will create the WebApi.xml file at the path bin\Debug\net7.0\ whenever you build the project.
Note: The NoWarn suppresses warnings if you don't have XML comments on all methods.

Now you can add multiple line and example for your custom documentation like this:

/// <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);
}

and the out put is like this(how ever I add some CSS and styles to swagger to make it prettier UI):
enter image description here

Upvotes: 1

Michael Smale
Michael Smale

Reputation: 663

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

Upvotes: 6

Abdessamad Jadid
Abdessamad Jadid

Reputation: 401

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.***

Upvotes: 0

danielj23
danielj23

Reputation: 101

Using Visual Studio 2019 (.net core 3.1), I'm able to use html remarks. It can be done all on one line using <br />. 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>

enter image description here

Upvotes: 3

Michael Freidgeim
Michael Freidgeim

Reputation: 28445

In SwashBuckle.AspNetCore <br /> and &lt;br /&gt(suggested in github) do not work. In <remarks> 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

Upvotes: 7

Ameya
Ameya

Reputation: 814

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

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

Upvotes: 2

Silvair L. Soares
Silvair L. Soares

Reputation: 1066

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

enter image description here

Upvotes: 2

nPcomp
nPcomp

Reputation: 9873

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>

Upvotes: 5

Sam Sole
Sam Sole

Reputation: 96

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

Upvotes: 8

Attila Szasz
Attila Szasz

Reputation: 3073

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

/// <br />

will cause a line break in the generated documentation.

Upvotes: 24

Related Questions