7

更新：我开始怀疑这是否是由于错误：

https://github.com/domaindrivendev/Swashbuckle/issues/590

但是那里建议的解决方法似乎不能解决我的问题。

我正在使用 Swashbuckle 为 C# ASP.NET Web API 项目生成 API 文档。

我的目标是允许以下内容作为有效 URL：

/endpoint/items/123/foo?param2=bar

将必需参数 (param1) 设置为“foo”，将可选参数 (param2) 设置为“bar”。我希望两个参数都包含在单个 C# 参数对象中。（带有其他可选参数，如 param3 等）。几个端点将使用相同的参数，我希望有一个代表参数的对象。

Swagger/Swashbuckle 的细节大多是一个黑匣子，我无法弄清楚。我在参数列表中得到了重复项。

重现问题的示例代码：

    // This endpoint is generating documentation the way I would like.
    [HttpGet]
    [Route("endpoint1/items/{id}/{param1}")]
    public string GetDataForParameters(int id, string param1, string param2 = null, string param3 = null)
    {
        return string.Format("Params: {1}, {2}, {3}", id, param1, param2, param3);
    }

    // This endpoint has the structure I would like, but I get duplicates for param1 in the documentation.
    [HttpGet]
    [Route("endpoint2/items/{id}/{param1}")]
    public string GetDataForParameters(int id, [FromUri(Name = "")]MyParams myParams)
    {
        return string.Format("Params: {1}, {2}, {3}", id, myParams.Param1, myParams.Param2, myParams.Param3);
    }

    public class MyParams
    {
        public string Param1 { get; set;}
        public string Param2 { get; set;}
        public string Param3 { get; set;}
    }

使用第二种方法，我在单个对象中接收参数。但 Swagger 显示“param1”的重复条目。

截图：Swagger 重复参数

如何使 Swagger/Swashbuckle 不显示“param1”的第二个条目？

具有这种结构的原因是我有多个端点，它们返回不同类型的数据，但它们使用通用参数。某些参数是必需的（以及 ID 的一个 prt），因此我们希望将这些参数包含在 URL 中，并在查询字符串中包含可选参数。我希望公共参数对象应该包括必需参数和可选参数。

使用 Visual Studio 2015 更新 1 创建的示例代码。默认 ASP.NET Web API 项目。将上面的代码添加到生成的 ValuesController.cs 中。安装包 Swashbuckle 5.3.1 + 依赖项。

4

2 回答 2

1

更新：找到了解决方法。它很丑：

  1. 在方法中引入显式重复参数。
  2. 将 JsonIgnore 属性添加到参数对象中的重复属性。

然后，Swagger 将获取此方法的参数和文档。ASP.Net 将参数分配给方法参数和参数对象，允许代码使用参数对象。

    /// <param name="param1">URL parameters must be documented on this level.</param>
    [HttpGet]
    [Route("endpoint2/items/{id}/{param1}")]
    public string GetDataForParameters(int id, string param1, [FromUri(Name = "")]MyParams myParams)
    {
        // the param1 method parameter is a dummy, and not used anywhere.
        return string.Format("Params: {1}, {2}, {3}", id, myParams.Param1, myParams.Param2, myParams.Param3);
    }

    public class MyParams
    {
        /// <summary>
        /// Cannot add documentation here, it will be ignored.
        /// </summary>
        [JsonIgnore]
        public string Param1 { get; set;}
        /// <summary>
        /// This is included. Querystring parameters can be documented in this class.
        /// </summary>
        public string Param2 { get; set;}
        public string Param3 { get; set;}
    }

我不会使用这种方法，它会让任何其他阅读代码的开发人员感到困惑。所以不幸的是，Swagger/Swashbuckle 在实践中迫使我更改我的（完全工作的）代码以生成文档。

除非有人能提出适当的解决方案，否则我认为最好的解决方案是使用简单的方法参数。

于 2016-02-18T11:17:40.460 回答
0

当 Swashbuckle 生成它的 swagger.json 文件时，它会查看路由和查询参数所以当你使用Get(string param1, string param2 ..)它时会自动告诉 Swashbuckle 这些参数是必需的（因为它们没有设置为= null）

当使用Get([FromUri(Name = "")]MyParams myParams) Swashbuckle 在模型中查找数据注释（System.ComponentModel.DataAnnotations）时，判断是否需要参数。

将 Param1 设置为必需

public class MyParams
    {
        [Required]
        public string Param1 { get; set;}
        public string Param2 { get; set;}
        public string Param3 { get; set;}
    }
于 2016-02-23T13:28:06.763 回答