Документация C# swagger для отдельных членов объекта body запроса

Question

Мы пишем swagger документацию, используя /// комментарии следующим образом:

/// <summary>
/// Create a new widget
/// </summary>
/// <param name="widget"></param>
[HttpPost("/create")]
[ProducesResponseType(typeof(IPayment), 200)]
[ProducesResponseType(typeof(ErrorResult), 400)]
[ProducesResponseType(typeof(ErrorResult), 404)]
public Task<IActionResult> CreateWidget([FromBody] Widget widget)
{

Теперь Widget является реализацией IWidget, и пользователь документации должен подробно знать, что означает каждый элемент данных Widget / IWidget, что является обязательным, что является необязательным, и допустимые значения.

Мы обнаружили, что единственное, пожалуйста, чтобы добавить это описание в

/// <param name="widget">very big multi line description</param>

Хотя это работает для конечного пользователя, есть ли лучший способ? Мы спрашиваем об этом, потому что это гораздо более легко поддерживать, если описания предоставляются в виде определения класса / интерфейса.

Answer 1

Точно так же, как вы документируете свои действия с /// комментарии вы также можете документировать свои модели

Вот пример:
http://swagger-net-test.azurewebsites.net/swagger/ui/index?filter=Location

Код для этого выглядит так:

/// <summary>
/// ## Geographic coordinates
/// ___
/// A **geographic coordinate system** is a coordinate system used in geography that enables every location on Earth
/// </summary>
public class Location
{
    /// <summary>**Latitude**: a geographic coordinate that specifies the north–south position of a point on the Earth's surface.</summary>
    /// <example>25.85</example>
    [Range(-90, 90)]
    public float Lat { get; set; }

    /// <summary>**Longitude**: a geographic coordinate that specifies the east-west position of a point on the Earth's surface.</summary>
    /// <example>-80.27</example>
    [Range(-180, 180)]
    public float Lon { get; set; }
}