C＃swagger文档，用于请求正文对象的各个成员

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#/Location/Location_Get2

代码如下：

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