使用swagger作為restful api的doc文檔生成

記得以前寫接口，寫完後會整理一份API接口文檔，而文檔的格式如果沒有具體要求的話，最終展示的文檔則完全決定于開發者的心情。也許多點，也許少點。甚至，接口總是需要适應新需求的，修改了，增加了，這份文檔維護起來就很困難了。于是發現了swagger，自動生成文檔的工具。

Swagger – The World's Most Popular Framework for APIs.

因為自強是以自信。swagger官方更新很給力，各種版本的更新都有。swagger會掃描配置的API文檔格式自動生成一份json資料，而swagger官方也提供了ui來做通常的展示，當然也支援自定義ui的。不過對後端開發者來說，能用就可以了，官方就可以了。

最強的是，不僅展示API，而且可以調用通路，隻要輸入參數既可以try it out.

效果為先，最終展示doc界面，也可以設定為中文：

以前總是看各種部落格來配置，這次也不例外。百度了千篇一律卻又各有細微的差别，甚至時間上、版本上各有不同。最終還是去看官方文檔，終于發現了官方的sample。針對于各種option的操作完全在demo中了，是以clone照抄就可以用了。

第一個是API擷取的包，第二是官方給出的一個ui界面。這個界面可以自定義，預設是官方的，對于安全問題，以及ui路由設定需要着重思考。

需要特别注意的是swagger scan base package,這是掃描注解的配置，即你的API接口位置。

當然，scan package 也可以換成别的條件，比如：

案例：

在配置檔案中，application.yml中聲明：

這個path就是json的通路request mapping.可以自定義，防止與自身代碼沖突。

API doc的顯示路由是：<code>http://localhost:8080/swagger-ui.html</code>

如果項目是一個webservice，通常設定home / 指向這裡：

就是上面的了。但是，注意到安全問題就會感覺困擾。首先，該接口請求有幾個：

除卻自定義的url，還有2個ui顯示的API和一個安全問題的API。關于安全問題的配置還沒去研究，但目前發現一個問題是在我的一個項目中，所有的url必須帶有query htid=xxx,這是為了sso portal驗證的時候需要。這樣這個幾個路由就不符合要求了。

如果不想去研究安全問題怎麼解決，那麼可以自定ui。隻需要将ui下面的檔案拷貝出來，然後修改請求資料方式即可。

3.後續閱讀文章：

<a href="http://yukinami.github.io/2015/07/07/%E4%BD%BF%E7%94%A8springfox%E7%94%9F%E6%88%90springmvc%E9%A1%B9%E7%9B%AE%E7%9A%84swagger%E7%9A%84%E6%96%87%E6%A1%A3/">http://yukinami.github.io/2015/07/07/%E4%BD%BF%E7%94%A8springfox%E7%94%9F%E6%88%90springmvc%E9%A1%B9%E7%9B%AE%E7%9A%84swagger%E7%9A%84%E6%96%87%E6%A1%A3/</a>

<a href="http://www.aichengxu.com/view/2500558">http://www.aichengxu.com/view/2500558</a>

唯有不斷學習方能改變！

-- <b>Ryan Miao</b>