如何將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，而不是手動檢查每個參數。 其他工具也可以查看模型的屬性，從而改善工具體驗。