使用swagger做爲restful api的doc文檔生成

• 本文做者：@Ryan Miao
• 本文連接：https://www.cnblogs.com/woshimrf/p/swagger.html
• 版權聲明： 本博客全部文章除特別聲明外，均採用 CC BY-NC-SA 3.0 許可協議。轉載請註明出處！

目錄

初衷
swagger介紹
在dropwizard中使用
在spring-boot中使用
配置
4.設定訪問API doc的路由
6. 設置在生產環境關閉swagger
參考：

初衷

記得之前寫接口，寫完後會整理一份API接口文檔，而文檔的格式若是沒有具體要求的話，最終展現的文檔則徹底決定於開發者的心情。也許多點，也許少點。甚至，接口老是須要適應新需求的，修改了，增長了，這份文檔維護起來就很困難了。因而發現了swagger，自動生成文檔的工具。

swagger介紹

首先，官網這樣寫的：

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

由於自強因此自信。swagger官方更新很給力，各類版本的更新都有。swagger會掃描配置的API文檔格式自動生成一份json數據，而swagger官方也提供了ui來作一般的展現，固然也支持自定義ui的。不過對後端開發者來講，能用就能夠了，官方就能夠了。

最強的是，不只展現API，並且能夠調用訪問，只要輸入參數既能夠try it out.

效果爲先，最終展現doc界面，也能夠設置爲中文：

在dropwizard中使用

詳細信息見另外一篇在dropwizard中使用Swagger

在spring-boot中使用

之前老是看各類博客來配置，此次也不例外。百度了千篇一概卻又各有細微的差異，甚至時間上、版本上各有不一樣。最終仍是去看官方文檔，終於發現了官方的sample。針對於各類option的操做徹底在demo中了，因此clone照抄就能夠用了。

github sample源碼

配置

1.須要依賴兩個包：

第一個是API獲取的包，第二是官方給出的一個ui界面。這個界面能夠自定義，默認是官方的，對於安全問題，以及ui路由設置須要着重思考。

2.swagger的configuration

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

固然，scan package 也能夠換成別的條件，好比：

3.在API上作一些聲明

案例：

4.設定訪問API doc的路由

在配置文件中，application.yml中聲明：

這個path就是json的訪問request mapping.能夠自定義，防止與自身代碼衝突。

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

若是項目是一個webservice，一般設定home / 指向這裏：

5.訪問

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

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

若是不想去研究安全問題怎麼解決，那麼能夠自定ui。只須要將ui下面的文件拷貝出來，而後修改請求數據方式便可。

6. 設置在生產環境關閉swagger

具體參考 http://www.cnblogs.com/woshimrf/p/disable-swagger.html