请求正文对象的各个成员的 C# swagger 文档

Question

我们正在使用 /// cmets 通过以下方式编写 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

与使用/// cmets 记录您的操作的方式相同，您还可以记录您的模型

这是一个例子：
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; }
}

---

看起来是这样的：

---

在发布或放置请求时，文档也可以在模型选项卡上看到：

https://swagger-net-test.azurewebsites.net/swagger/ui/index?filter=Company

和往常一样在模特下：