原文地址：http://www.cnblogs.com/Erik_Xu/p/5638381.html
你需要爲客戶編寫Api調用手冊？你需要測試你的Api接口？你需要和前端進行接口對接？那麼這篇文章應該可以幫到你。本文將介紹創建Web Api 幫助文檔頁面的兩種方式，Microsoft Help Page和Swashbuckle Help Page。
編寫RESTful的Web Api
/// <summary>
/// 股票數據接口
/// </summary>
[RoutePrefix("api/stocks")]
public class StocksController : ApiController
{
private readonly List<Stock> _stocks;
/// <summary>
/// 構造函數
/// </summary>
public StocksController()
{
_stocks = new List<Stock>
{
new Stock{Symbol = "000001", Name = "平安銀行", Exchange = "深證交易所"},
new Stock{Symbol = "000002", Name = "萬科A", Exchange = "深證交易所"},
new Stock{Symbol = "000003", Name = "PT金田A", Exchange = "深證交易所"},
new Stock{Symbol = "000004", Name = "國農科技", Exchange = "深證交易所"},
new Stock{Symbol = "000005", Name = "世紀星源", Exchange = "深證交易所"}
};
}
/// <summary>
/// 獲取股票列表
/// </summary>
/// <returns>股票列表</returns>
[HttpGet]
public IEnumerable<Stock> List()
{
return _stocks;
}
/// <summary>
/// 獲取指定股票
/// </summary>
/// <param name="symbol">股票代碼</param>
/// <returns>指定股票</returns>
[HttpGet(), Route("{symbol}", Name = "Get")]
public IHttpActionResult Get(string symbol)
{
var stock = _stocks.SingleOrDefault(n => n.Symbol == symbol);
if (stock == null)
{
return NotFound();
}
return Ok(stock);
}
/// <summary>
/// 添加一支股票
/// </summary>
/// <param name="stock">股票信息</param>
[HttpPost]
public IHttpActionResult Create(Stock stock)
{
return CreatedAtRoute("Get", new { symbol = stock.Symbol }, stock);
}
/// <summary>
/// 更新一支股票
/// </summary>
/// <param name="stock">股票信息</param>
[HttpPut]
public IHttpActionResult Update(Stock stock)
{
if (_stocks.All(n => n.Symbol != stock.Symbol))
{
return NotFound();
}
return StatusCode(HttpStatusCode.NoContent);
}
/// <summary>
/// 部分更新一支股票
/// </summary>
/// <param name="symbol">股票代碼</param>
/// <param name="form">需要更新的股票信息</param>
[HttpPatch, Route("{symbol}")]
public IHttpActionResult PartialUpdate(string symbol, PartialForm form)
{
if (_stocks.All(n => n.Symbol != symbol))
{
return NotFound();
}
return StatusCode(HttpStatusCode.NoContent);
}
/// <summary>
/// 刪除一支股票
/// </summary>
/// <param name="symbol">股票代碼</param>
/// <returns>是否刪除成功</returns>
[HttpDelete, Route("{symbol}")]
public IHttpActionResult Delete(string symbol)
{
if (_stocks.All(n => n.Symbol != symbol))
{
return NotFound();
}
return Ok(true);
}
/// <summary>
/// 這個方法不會顯示到幫助頁面
/// </summary>
[HttpGet, Route("hide")]
[ApiExplorerSettings(IgnoreApi = true)]
public void NotShow()
{
}
}
Microsoft Help Page
1.在Nuget添加Help Page組件。
組件添加完後，會自動生成幫助頁面，文件存在區域（Areas）中
2.註冊區域（Areas）
在Global.asax文件中的Application_Start()方法添加以下代碼：
AreaRegistration.RegisterAllAreas();
瀏覽生成的幫助頁面：http://localhost:xxxx/help
Web API的方法列表已經顯示出來了，但是方法的描述還是默認的描述。
3. 修改配置文件生成位置
右鍵項目屬性，指定輸出xml。
修改Areas\HelpPage\App_Start\HelpPageConfig.cs中register方法裏指定的xml路徑爲上述指定輸出的路徑。
再查看幫助頁面，方法描述已經和代碼註釋一致。
注：這裏可根據需要把Area中對應頁面的英文詞條更新成中文，當然樣式也可以調整。
4.添加測試工具
在Nuget添加Test Client組件。
在Areas\HelpPage\Views\Help\Api.cshtml添加以下代碼：
@Html.DisplayForModel("TestClientDialogs")
@section Scripts {
<link type="text/css" href="~/Areas/HelpPage/HelpPage.css" rel="stylesheet" />
@Html.DisplayForModel("TestClientReferences")
}
再次運行Help Page，每個API說明頁面的右下角會多一個測試的按鈕。
4.參考
http://www.asp.net/web-api/overview/getting-started-with-aspnet-web-api/creating-api-help-pages
Swashbuckle Help Page
1.在Nuget添加Swashbuckle組件。
然後就可以瀏覽生成的幫助頁面：http://localhost:xxxx/swagger
Web API的方法列表已經顯示出來了，但是方法的描述還沒有顯示出來。
2. 修改配置文件生成位置
右鍵項目屬性，指定輸出xml。
找到SwaggerConfig.cs
把 c.IncludeXmlComments(GetXmlCommentsPath())的註釋去掉
實現GetXmlCommentsPath()方法，指定xml路徑爲上述指定輸出的路徑。
再查看幫助頁面，方法描述已經和代碼註釋一致。
2. 常見異常
用Nuget引用dll的時候，它會在config中添加依賴項信息，但偶爾會沒添加，這時會出現Could not load file or assembly 'XXX' or one of its dependencies. The located assembly's manifest definition does not match the assembly reference. (Exception from HRESULT: 0x80131040)異常。
此時只要在config中添加對應的依賴項就好
4.幫助頁面詞條及樣式調整
如果要修改或編輯Swashbuckle Help Page的樣式或詞條，需要編輯SwaggerConfig.cs，相對Microsoft Help Page可能要複雜一點（我只改過Microsoft的，沒改過Swashbuckle的）。具體如何修改可參考：https://github.com/domaindrivendev/Swashbuckle
簡單總結
Swashbuckle Help Page搭建起來相對會比較簡單，但是樣式（自帶swagger logo）和詞條修改會較麻煩一點，因此，比較適合作爲內部接口說明幾接口調用測試。
Microsoft Help Page搭建起來相對要麻煩一點點，但是樣式和詞條修改會方便一點，因此，比較適合作爲外部接口調用使用文檔。