前段時間想對所做的WebAPI加入文檔功能,方便調用接口的同事查閱,上網了解到Swagger,在學習使用Swagger的時候,網上資料算是比較多,但個人認為能夠詳細說明白的比較少,思路都有說到,但具體的就沒說,或沒實例說明,讓初學者容易搞錯(我也走了好些彎路),現把自己查閱資料,並結合個人實際使用的結果,發上來,一來供有緣人參考,二來自己也有個筆記。
環境:VS2013、.NET Framework 4、Swagger5.5.3
一、新建WebAPI項目,利用NuGet安裝Swagger
網上有人說要安裝Swashbuckle和Swagger UI for .NET,可能是Swashbuckle的版本升級了,我后來發現只安裝Swashbuckle即可
二、設置項目生成XML文檔的位置
三、Swagger安裝好后在App_Start下有SwaggerConfig.cs,修改它,設置讀取項目的XML文檔
到此,Swagger已可正常工作了,啟動項目,在瀏覽器地址后加/Swagger,即可看到生成效果
Swagger的擴展(此功能參考整合網上的資料得出,如果相應網友有所冒犯,敬請原諒)
1、美化及漢化
新建一SwaggerExt文件夾,增加Swagger樣式、腳本兩個文件(具體看Demo),並都設置為嵌入的資源
修改SwaggerConfig.cs文件
啟動項目,即可看到效果
二、增加控制器說明
增加CachingSwaggerProvider.cs文件,內容見Demo
修改SwaggerConfig.cs文件
啟動效果
如果能把這個說明放左邊,接着控制器名稱,那就更好了,但我沒找到辦法,如果有網友有辦法,麻煩轉告一下
三、隱藏某接口說明
增加HiddenApiFilter.cs,內容見Demo
修改SwaggerConfig.cs文件
對要隱藏的接口加入[HiddenApi]
啟動效果
到此,基本上對Swagger的使用已差不多了,附上我Demo的代碼
如有對Swagger使用心得上有更好見解的,請轉告一下