Как добавить разрыв строки в документацию Swashbuckle?

Я создаю документацию для api, реализованной в Web Api 2, используя swagger/swashbuckle.

Единственными признанными тегами документации xml являются <summary>, <remarks> и <param>.
Это означает, что я не могу использовать тег <para> для форматирования текста в новых строках или абзацах, все создается как непрерывный длинный абзац в записи Notes Notes.

Есть ли способ сделать это?

Ответы

Ответ 1

Еще один способ достичь - создать пользовательский OperationFilter и использовать теги документации xml, как описано в:

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

Надеюсь, что это поможет

Сэм

Ответ 2

Я обнаружил, что вы можете просто добавить теги <br /> к комментариям, чтобы достичь этого.
Добавление:

/// <br />

приведет к разрыву строки в сгенерированной документации.

Ответ 3

В SwashBuckle.AspNetCore <br/> и &lt;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

Ответ 4

Ни одно из опубликованных решений не будет работать с более новой версией Swagger. Если вы хотите разделить новую строку между строками комментария, вы должны добавить /// для новой строки. Это делает комментарии метода длинными, но они будут более читабельными в документации Swagger.

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

Ответ 5

Используя приведенную ниже структуру, будут работать как пользовательский интерфейс Swashbuckle, так и пользовательский интерфейс ReDoc:

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

Важное примечание: не игнорируйте пробелы в конце каждой строки

enter image description here

Ответ 6

Если ни один из ответов не сработал для вас, в некоторых случаях сработал частично, как это было со мной.

Вы можете использовать <br></br>. Не используйте </br>. Это может иногда нарушать XML. Visual Studio показала плохое форматирование XML для <br/>