項目中你可能已經使用到了swagger,或許你並沒有對它過於留意,比如說springfox、swagger-springmvc、swagger-ui他們之間的關係是什麼,springfox原理是什麼。
先看一個pull下來就能啓動的spring-boot,swagger-ui集成demo
- 獲取代碼
git pull https://github.com/moxingwang/swagger.git
- 啓動
cd swagger mvn spring-boot:run
- 訪問
http://localhost:8080/sw/swagger-ui.html
自此一個非常方便又簡單的swagger-ui集成好了,寫完業務邏輯代碼可以立馬公佈restful api給前端調用。
具體使用
- 基於springfox使用swagger非常簡單,只需要maven依賴以及少量config配置就可以實現,上面的demo中都有體現,或者直接訪問springfox的github上面的demospringfox/springfox-demos 。
- springfox更詳細配置請參考官方文檔Springfox Reference Documentation。
- swagger annotation具體使用 Swagger-Core Annotations,這裏面有詳細的annotation描述。
特別注意事項
雖然說swagger是個好東西,但是使用中切不可以忽略的一個問題--【安全】。dev uat1環境中你可以開放swagger給前端或者測試,千萬不要把它開放給了生產,如果你的swagger ui不小心放到了生產,那是一件多麼可怕的事情,真可以來個‘一鍋端’,切記切記。官網文檔有相關的安全配置http://springfox.github.io/springfox/docs/current/#configuring-security-schemes-and-contexts-an-overview。也可以在不同環境配置中添加要給變量來控制,swagger ui是否可用(https://github.com/moxingwang/swagger.git)。
@Value("${swagger.switch}")
private boolean swaggerSwitch;
@Bean
public Docket api() {
Docket docket = new Docket(DocumentationType.SWAGGER_2);
if (swaggerSwitch) {
docket.enable(true);
} else {
docket.enable(false);
}
docket.apiInfo(apiInfo()).select().paths(PathSelectors.any()).build();
return docket;
}
其他
如若你在spring-boot中使用swagger還嫌麻煩,想要直接一個註解搞定,建議你看SpringForAll/spring-boot-starter-swagger這個項目。
搞明白swagger,springfox是什麼
swagger
Swagger 是一款目前世界最流行的API管理工具,是一個規範和完整的框架,用於生成、描述、調用和可視化 RESTful 風格的 Web 服務。文檔提供了一個方法,我們可以用指定的 JSON 或者 YAML 摘要來描述你的 API,包括了比如 names、order 等 API 信息。你可以通過一個文本編輯器來編輯 Swagger 文件,或者你也可以從你的代碼註釋中自動生成。各種工具都可以使用 Swagger 文件來生成互動的 API 文檔。你需要具體閱讀這裏What Is Swagger?來理解。
Swagger擁有衆多不同語言和平臺的開源實現與工具,他有很多實現方式,非常方便,並且支持語言特別多,詳細請查看(一定要看一眼,就知道他有多強大)Tools and Integrations。
這裏也可以參考Swagger Annotation 詳解(建議收藏)這篇文章查看相關幾個組件的中文介紹。
springfox
springfox是java對swagger的一個具體實現。springfox的前身是swagger-springmvc,用於springmvc與swagger的整合。它內部會自動解析Spring容器中Controller暴露出的接口,並且也提供了一個界面用於展示或調用這些API。
要分分鐘瞭解springfox的原理,請參考阿里雲社區API管理工具Swagger介紹及Springfox原理分析這篇文章。
最後再來看一篇文章Swagger 和 Springfox-Swagger 的關係,加深你對Swagger和Springfox-Swagger的理解。
總結
- 如果你後臺開發,提供restful接口給前端。建議你使用swagger-ui提供restful的接口文檔描述。
- 如果你是接口設計者,建議你使用Swagger Editor設計。
- 如果你是接口調用方,想快速生成接口調用代碼,很簡單,你只需要使用Swagger Editor生存client代碼就行了,十分方便。