如何让 Swagger 显示从 API 返回的对象示例？

Question

我是第一次创建一组 API。这是其中一种方法：

    // GET: api/Doors/0
    /// <summary>
    /// Get a list of all doors for a given organization.
    /// </summary>
    /// <param name="organizationSys">The Organization ID for which all doors should be retreived.</param>
    /// <returns></returns>
    [Route("{organizationSys:int}")]
    public IHttpActionResult Get(int organizationSys)
    {
        try
        {
            Dictionary<string, object> parameters = new Dictionary<string, object>();
            parameters.Add("@OrganizationSys", organizationSys);
            List<Door> doors = Repository<Doors>.GetList("WHERE OrganizationSys = @OrganizationSys", parameters).ToList();
            if (doors == null || doors.Count() == 0)
                return Content(HttpStatusCode.NotFound, RejectionMessage.NoItemsFound);

            return Ok(doors);
        }
        catch (Exception ex)
        {
            return Content(HttpStatusCode.BadRequest, ex.Message);
        }
    }

我已经为此端点设置了单元测试，它运行良好。但是，我有一个问题。

在 Swagger 中，我想展示一个将 returned 的数据对象示例。该方法中唯一的 return 类型是 IHttpActionResult 所以我并不惊讶它没有在 Swagger 中显示数据模型。那么，我需要用这个方法改变什么才能使 return 对象（在本例中为 List<Door>）更加可见？

Swashbuckle 支持这个吗？

谢谢！

Answer 1

这应该很简单：

[Route("{organizationSys:int}")]
[ProducesResponseType(typeof(List<Door>), 200)]
[ProducesResponseType(typeof(string), 400)]
public IHttpActionResult Get(int organizationSys)

请注意，由于您有 2 个退出点：一个带有数据的正常 return 和一个捕获 return 错误消息，我在上面的示例中定义了两种可能的结果类型：

http:200（确定）与 List<Door>
http:400(BadRequest) 与 string

Swashbuckle Swagger 基础架构将读取这些内容并提供非常粗略的 这些案例的数据示例。

但是，如果您需要更详细的示例（即具有一些合理的字段值），那么您将必须实施so-called“示例提供程序”。 See here for details and quick tutorial，简而言之：

[SwaggerRequestExample(typeof(DeliveryOptionsSearchModel), typeof(DeliveryOptionsSearchModelExample))]
public async Task<IHttpActionResult> DeliveryOptionsForAddress(DeliveryOptionsSearchModel search)

和

public class DeliveryOptionsSearchModelExample : IExamplesProvider
{
  public object GetExamples()
  {
    return new DeliveryOptionsSearchModel
    {
        Lang = "en-GB",
        Currency = "GBP",
        Address = new AddressModel
        {
            Address1 = "1 Gwalior Road",
            Locality = "London",
            Country = "GB",
            PostalCode = "SW15 1NP"
        },
        Items = new[]
        {
            new ItemModel
            {
                ItemId = "ABCD",
                ItemType = ItemType.Product,
                Price = 20,
                Quantity = 1,
                RestrictedCountries = new[] { "US" }
            }
        }
    };
}

示例提供程序以非常简单的方式工作：无论提供程序 returns 是什么，它都被序列化为 JSON 和 returned 作为 的示例给定数据类型。就这样。

现在，如果您的方法 returned DeliveryOptionsSearchModel，提供者将直接使用上面的数据。

或者，如果您的方法 return 编辑了一个更大的对象，由 DeliveryOptionsSearchModel 和其他一些对象组成，那么 Swagger 会将此提供程序用于响应示例的一部分，而其他提供程序)（或默认粗略示例）用于大对象的所有其他部分。

以上均为Net Core。

如果您使用'normal' Net 4.5/4.6/4.7，则此方式不可用，因为属性class 不存在。在 AspMvc for Net 4.x 中，只有 [ResponseType(typeof(..))] 属性允许定义单个 return 类型。大多数时候都可以。但是，如果您真的需要区分 return 类型与响应代码，或者如果您需要提供好的示例，那就是个问题了。

但是！一些好人已经解决了这个问题。参见 this article。它描述了 NuGet Swagger.Examples，我相信它是为了 non-core，它旨在提供更好的结果描述。

它定义了另一个属性 - [SwaggerResponse(HttpStatusCode.OK, Type=typeof(IEnumerable... 来定义可能的结果代码和结果类型，并为 Swagger 提供插件以使用该属性。

它还提供了另一个属性，[SwaggerResponseExample...，允许你定义result-example提供者，它可以提供一个自定义好的数据示例，就像上面描述的Core的IExampleProvider。整洁！

Answer 2

Core 的 IOperationFilter 没有模式注册表作为 Apply 方法实现中的参数

    public void Apply(Operation operation, OperationFilterContext context)
    {
        throw new NotImplementedException();
    }

Answer 3

对于 ASP.NET WebApi2，您可以使用属性 SwaggerResponse。这个你可以指定状态码和返回类型。

[SwaggerResponse(System.Net.HttpStatusCode.OK, Type = typeof(List<Door>))]
[SwaggerResponse(System.Net.HttpStatusCode.NotFound, Type = typeof(string))]

您可以在此处找到更多信息：https://mattfrear.com/2015/04/21/generating-swagger-example-responses-with-swashbuckle/

如何让 Swagger 显示从 API 返回的对象示例？

How to make Swagger show examples of objects returned from the API?

.net

c#

api

swagger

swashbuckle