如何在Swagger UI中为我的请求/响应提供示例数据？

Question

我正在使用WebAPI 2和OWIN开发一个Web服务。我的目标是使用Swashbuckle添加一些文档。

按照我的方法：

/// <summary>
/// La mia descrizione...
/// </summary>
/// <param name="id">Identificativo</param>
/// <param name="list">Una lista</param>
[HttpPut]
[Route("~/api/v1/documents/{id}/attribute")]
public IHttpActionResult Put(int id, List<AttributeDto> list)
{
    _myService.Create(list, id);
    return Ok();
}

在我的 AttributeDto 类代码下面：

using Newtonsoft.Json;

namespace WebApi.Dtos
{
    public class AttributeDto
    {
        [JsonIgnore]
        public int Id { get; set; }

        [JsonIgnore]
        public int OtherId { get; set; }

        public string Label { get; set; }

        public string Value { get; set; }
    }
}

如果我打开Swagger UI，我可以查看一个带有自动生成数据的示例部分：

如何自定义自动生成的数据，以便图片中的JSON如下所示：

[
  {
    "label": "Etichetta di esempio",
    "value": "Valore di esempio"
  }
]

Answer 1

我会建议您使用Swagger-Net而不是swashbuckle。 您需要做的就是用xml示例注释装饰definition属性，如下所示：

public class AttributeDto
{
    [JsonIgnore]
    public int Id { get; set; }

    [JsonIgnore]
    public int OtherId { get; set; }

    /// <example>Etichetta di esempio</example>
    public string Label { get; set; }

    /// <example>Valore di esempio</example>
    public string Value { get; set; }
}

这被提议为swashbuckle但尚未合并：
https://github.com/domaindrivendev/Swashbuckle/pull/1091
Swagger-Net是我的Swashbuckle的分支，但我已经合并了许多不错的功能并修复了许多错误。

Answer 2

一个选项是使用ISchemaFilter（在SwaggerConfig.cs上），这是一个例子：

cmd.exe /c "dfsutil property SD grant \\domain\group "domain\SecurityGroup1:RX""

我个人不喜欢这个解决方案，因为我们必须在两个不同的文件中维护一个班级的信息......