WebAPI——自動生成幫助文檔

Web Api 自動生成幫助文檔

 

新建Web Api項目以後，會在首頁有API的導航菜單，點擊便可看到API幫助文檔，不過很遺憾，Description 是沒有內容的。

怎麼辦呢？

第一步：

若是用VS2013 新建項目的（VS2012沒試過），項目中會有 Areas/HelpPage 這樣的目錄，你沒看錯，文檔就是這貨生成的。

若是要是刪除了或者，沒有這個目錄怎麼辦呢？不要緊，你只須要使用NuGet添加  【Microsoft.AspNet.WebApi.HelpPage】這貨，而後你就發現，你的項目自動添加了 Areas/HelpPage這一坨

 

第二步：

選中項目，右鍵，屬性，生成，選擇下面的XML 文檔文件，目錄本身填寫，以下圖：

 

第三步：

找到 Areas/HelpPage/App_Start  目錄下的HelpPageConfig.cs 文件，Register 方法，添加一行代碼：

1 config.SetDocumentationProvider(new XmlDocumentationProvider(HttpContext.Current.Server.MapPath("~/Areas/HelpPage/WebApiHelp.XML")));

而後生成一下，啓動項目，點擊API看看

 

而後你就會感受，本身棒棒噠。。。

 

Ps: 生成API 文檔說明的前提是你的 寫註釋！！！！！

 

 

--------------------------------------------------------------------華麗麗的分割線---------------------------------------------------------------------------------------------------------

Update ：

這樣以後，你生成項目一看，幾百個警告：警告    2    缺乏對公共可見類型或成員「XXX.XXXXX.XXX」的 XML 註釋    D:\XXXX\XXX\SampleDirection.cs    什麼的
說的很清楚，對，就是你沒給 屬性和類 加上註釋，怎麼辦呢？一條一條加註釋，顯然不可能。

因而，選中項目，右鍵屬性，禁止顯示警告輸入:1591,如圖：

 

在生成一下看看就OK了

 

 還有一點親身體驗須要告知：

areas的命名空間必定要是位於當前API 項目的同一個命名空間下，固然通常不須要考慮這些，可是因爲的項目是在已有的基礎上修改的，就修改了命名空間的名稱，可是開始沒用到幫助文檔，就沒改Areas部分的命名空間，測試老是看不到幫助文檔，說是依賴部分找不到或是名稱已修改，後來才煥然大悟，終於看到幫助文檔的界面。

接下來就看看寫註釋有哪些技巧了，待續……