在Web API中使用Swagger-UI開源組件（一個深坑的解決）

介紹：

Swagger-Ui是一個非常棒的Web API說明幫助頁，具體詳情可自行Google和百度。

官網：http://swagger.io/    GitHub地址：https://github.com/swagger-api/swagger-ui

 

使用：

Swagger-Ui是一個用純前端語言開發的項目，所有強大的功能全靠JS實現。為了能在.Net的Web API項目中使用，我們借用domaindrivendev開發的Swashbuckle進行配置。配置方法如下：

1、在Nuget中安裝Swashbuckle，它會依賴安裝Swashbuckle.Core。安裝完成之后，會在你的App_Start目錄下增加SwaggerConfig.cs文件。

2、右鍵你的Web API項目，選擇屬性，然后點擊生成。勾選XML文檔文件。上面輸出路徑自己選好。這是我的配置方式

3、在SwaggerConfig.cs文件中，取消c.IncludeXmlComments(GetXmlCommentsPath());的注釋，並為該方法寫代碼，其實就是查找第二部生成的XML文件

4、在你項目的合適位置（如：Views\Shared\_Layout.cshtm）增加訪問路徑

5、運行起你的Web API項目，點擊Swagger。你就可以看到Swagger頁面了。  還是非常簡單易用的。  

 

 

 

那么問題來了：

既然Swagger-Ui是一個純前端語言開發的工具，那我想自定義一下它，應該很容易吧。事實呢，的確很容易（深坑）。

我們有兩種方法：

第一種：去Swagger-Ui官方網站，下載最新的源代碼，自己配置。 反正也就是讀取你生成的Json文件，這里就不多說了，因為我不會。

第二種：我們既然用的是domaindrivendev開發的Swashbuckle。而且這個也是開源的（深坑），我們下下來源碼，自己編譯一下，修改修改就可以了，結果這個坑我就跳了。

 

廢話不多說了，當時的情況是源碼下下來，各種看不懂，不管他，直接替換掉Nuget的Swashbuckle.Core引用，然后運行起來，發現缺失了一堆堆JS、CSS文件。但是在源代碼中卻根本沒發現那些缺失的文件，吭哧吭哧找了好久。猜想以為是通過網絡獲取，但偏偏在在Chorme中調試，發現全是本地文件。最后各種無果。

 

只好去反編譯一下Nuget下下來的包，掏出.NET程序員的神器ILSpy。發現在下下來的dll文件中，缺失的文件全在資源里面，如圖 

突然豁然開朗，原來是額外有資源文件，那我們就加進去吧。    

但是結果發現，我根本不能按照反編譯的那樣，按照一定的路徑和格式添加那些文件！！！不信你自己可以試試，看看加進去的資源文件是什么樣的方式和路徑。

 

嘗試了N種方法之后，依然無果。只好去求助，最后在iFish的指引下，發現了這個....

好吧，問題到這里算是解決了。

在項目的csproj文件中，作者配置了資源文件的導入。但是卻在發布代碼的時候，忘了把Swagger-Ui的代碼加進去，而且還是用這種這么冷門的方法導入的資源文件。  真是無力吐槽。   不過也算是學到了新的東西（坑）。

---------------------------------------------------------------

2017-04-25更新，這種方式在netcore中簡直太常見了。。

---------------------------------------------------------------

最后稍微修改了一下，把Swagger-Ui集成到Swashbuckle.Core中，小修改如下

<!-- Automatically embed swagger-ui files. Construct name so resource can be retrieved by swagger-ui relative path -->
  <ItemGroup>
    <EmbeddedResource Include="swagger-ui\dist\**\*.*">
      <LogicalName>%(RecursiveDir)%(FileName)%(Extension)</LogicalName>
      <InProject>false</InProject>
    </EmbeddedResource>
  </ItemGroup>

問題解決！剩下的就是前端的工作了，自己自定義一下。比如漢化，官方自帶語言包，引用一下兩個JS文件即可：

   <!--漢化翻譯-->
    <script src='lang/translator-js' type='text/javascript'></script>
    <script src='lang/zh-cn-js' type='text/javascript'></script> 

 

 

學習過程中查找的資料：

Swagger項目主頁 ：  https://github.com/swagger-api/swagger-ui  

Swashbuckle 項目主頁： https://github.com/domaindrivendev/Swashbuckle  


這三個是國內有人研究分享的文章 ：

 

https://github.com/helei112g/swagger-ui

http://www.cnblogs.com/Flyear/p/4870373.html 

http://www.cnblogs.com/yxlblogs/p/4075932.html