背景

　　客戶在使用REST介面來獲取資料，比如要根據group的名字來獲取group的所有資訊。假如是一個這樣的REST API：/groups/groupname。但是使用者的groupname中包含slash(“/”)，URL就變成/groups/groupname/groupname這樣的形式。我們知道，多了一個slash之後，REST就會認為這是另外的資源，所以對於使用者的請求，是沒有對應的資源返回給使用者的（後臺是沒有對應的方法接收請求）。對於這個問題的解決思路和多種解決辦法，在這篇文章中不會詳述，我只是說我採用的辦法。增加一個新的API：/groups/**，這個新的API可以接收使用者請求中包含slash這種情況。

　　因為專案中的所有RESTAPI都使用SwaggerUI展示了出來，當我增加了這個新的API之後，它也出現在了SwaggerUI上面，而我不想把這個API暴露給使用者，我該怎麼辦呢？

　　上網查了很多資料，發現一些解決辦法，比如在註解中將hidden設定為true，或者在什麼pathSelector中配置你不想顯示的url……當我在專案中試的時候，發現解決辦法中的註解來自不同的包；即便專案中有相同的註解，我的專案中該註解卻沒有hidden屬性（版本問題）；或者是要修改的配置類中的方法在我專案中根本就沒有。Make me confused！怎麼和swagger相關的有這麼多不同的包。所以針對我在查詢過程遇到的幾種包查了查區別，終於對他們的關係和各自的實現方式有了個清晰的看法。

• difference between springfox and com.mangofactory
• ways of integrating swagger and spring

導讀

　　本篇文章分為三個部分，第一部分介紹我理解的Swagger UI；第二部分由不同的包引出與Swagger UI整合的不同方式。第三部分給出實踐性的Demo，放在下一篇文章裡敘述。

什麼是Swagger

• Swagger是將你寫的介面文件化的工具。
• Swagger UI能將專案的介面以UI的形式展現出來，並可以在此UI上檢視各個介面的定義，並可以直接使用此介面訪問資料。Swagger UI是Swagger的一部分。

（以上是用自己的話理解的，更準確的解釋請看下圖）

與Swagger整合三種方式

Here is an explanation of the different libraries.

Springfox is in a sense v2 of the swagger library that used to be packaged as mangofactory. What happened was we transitioned from using a private repo to creating a github organization so support development as a team.
(Springfox是swagger庫的v2版本，之前都打包成mangofactory。把庫升級為spingfox是為了將原有的私有庫轉變成github組織以支援團隊開發。)

In short mangofactory evolved into springfox which supports 2.0 version of swagger spec (in addition to 1.2). To be clear springfox and its predecessor supports spring mvc.
（mangofactory發展成了springfox，從而支援swagger的2.0規範（1.2除外），springfox和mangofactory都支援springmvc。）

io.swagger is the mother ship if you will. It has great support for spring and jax-rs. So if you’re looking for support for Jax-rs based services using spring or otherwise that’s a great option.
（io.swagger主要來支援spring和jax-rs，jax-rs是J2EE對RESTful API的支援，比如你專案中使用了spring，jax-rs，沒用springmvc，可以使用這個包與swagger整合。）

總結

　　如果你的專案使用jax-rs來實現RESTful介面，你就用io.swagger來整合swagger；如果你的專案使用springmvc來實現RESTful介面，最新的方法還是推薦使用springfox，但是也存在還在繼續使用mangofactory來實現與swagger整合的專案。