推薦一個接口文檔自動生成工具Swagger

本文包括兩個部分：

1. webapi中使用swagger
2. 修改webapi的路由和默認參數

WebApi中使用swagger

新建一個webapi項目

項目打開之後，選擇 引用，右鍵，管理NuGet程序包

瀏覽，搜索swagger，選擇第一個swashbuckle，安裝

安裝好之後，右鍵項目，選擇屬性，生成，在下面的輸出那裏勾選：XML文檔文件，如果沒有自動填充好路徑，需要自己填寫一下，文件名可以自己取。

打開App_Start文件夾下的SwaggerConfig.cs文件，新增一個如下方法：

private static string GetXmlCommentsPath()
{
    return System.String.Format(@"{0}\bin\WebApiDemo.xml", System.AppDomain.CurrentDomain.BaseDirectory);
}

其中WebApiDemo.xml這個文件名要和自己在前一步填寫的文件名一致

搜索GetXmlCommentsPath，下面能搜到已經註釋了，自己把註釋放開，要是沒搜到，就自己手動寫一下c.IncludeXmlComments(GetXmlCommentsPath());注意要寫在register方法裏面

打開valuescontroller，自己寫一些註釋

運行項目，在根路徑後面直接加swagger，就會自動跳轉到文檔，如：http://localhost:8970/swagger，能看到我們寫的一些註釋

修改webapi的路由和默認參數

在實際應用中，完全使用webapi的restful風格的api設計是比較少見的，請求方式一般也只使用get請求和post請求，所以我們做一些修改，使用的是類似restful風格的api設計，修改一下webapi的路由配置

把valuescontroller做一些修改

/// <summary>
/// ValuesController的註釋
/// </summary>
public class ValuesController : ApiController
{
    /// <summary>
    /// 獲取列表
    /// </summary>
    /// <returns></returns>
    [HttpGet]
    public IEnumerable<string> GetList(int pageIndex, int pageSize, string search = "")
    {
        return new string[] { "value1", "value2" };
    }

    /// <summary>
    /// 設置鍵值對
    /// </summary>
    /// <param name="value"></param>
    [HttpPost]
    public string PostData([FromBody]string key, [FromBody]string value = "value")
    {
        return "{\"" + key + "\":\"" + value + "\"}";
    }

}

重新運行，能看到文檔變成了如下，必填的參數顯示required，非必填的參數可以不用填，post請求的參數也顯示在文檔裏