如何将Swagger与来自Web API操作方法的动态参数一起使用？

Question

我以非标准的方式编写Web API控制器，在其中我将参数作为动态对象获取。

这会引起NSwag问题。 由于方法定义中没有参数，因此NSwag无法生成所需的内容。

我想知道在这种情况下是否可以使用NSwag。 也许有些属性可以添加到方法中，以便NSwag能够生成API？

[HttpPost]
[ActionName("create-account")]
public IHttpActionResult CreateAccount()
{
    var body = Request.Content.ReadAsStringAsync().Result;

    dynamic json = Utils.GetJsonBody(body);

    if (!Utils.GetJsonPropertyValueByPropertyName<String>(json, "email", out String email))
    {
        return Content(HttpStatusCode.BadRequest, "Please provide a valid email.".AsApiMessageResult());
    }

    if (!Utils.GetJsonPropertyValueByPropertyName<String>(json, "name", out String name))
    {
        return Content(HttpStatusCode.BadRequest, "Please provide an account name.".AsApiMessageResult());
    }

    if (!Utils.GetJsonPropertyValueByPropertyName<String>(json, "domain", out String domain))
    {
        return Content(HttpStatusCode.BadRequest, "Please provide a valid domain.".AsApiMessageResult());
    } 

Answer 1

关于Swagger的事情是，它使用方法的签名来生成其代码工作方式的文档。 绕过所有普通的Web API并选择读取原始的HTTP请求意味着Swagger无法看到您在做什么，这使其很难自动确定您的代码在做什么。 您在读取原始请求和使用动态数据时所采用的技术还有许多其他缺点。

• 您不会为您的对象获得Intellisense
• 它不是功能性的，这意味着很难通过查看方法来判断输入和输出的含义，这使得理解起来更加困难
• 很难对代码进行单元测试，因为现在您必须为Web API控制器建立HTTP请求
• 它需要比使用适当的对象处理更多的代码

相反，我们应该定义一个适当的模型来发布到我们的API。 这将使Web API能够完成其工作，模型绑定程序将处理将请求转换为CreateAccountRequest实例的过程。

public class CreateAccountRequest
{
    public string Email { get; set; }

    public string Name { get; set; }

    public string Domain { get; set; }
}

然后，我们可以让我们的操作方法将这个类的实例作为参数。

[HttpPost]
[ActionName("create-account")]
public IHttpActionResult CreateAccount(CreateAccountRequest request)
{
    //now here you can validate the request if you want
}

Swagger现在应该能够理解此方法，从而允许NSwag生成有用的客户端。

请注意，您应该研究Web API为模型验证提供的内置工具，而不是执行自定义C＃ 验证 。 然后，您所需要做的就是检查ModelState，而不是手动检查每个参数。 其他工具也可以查看模型的属性，从而改善工具体验。