API管理-捨棄springfox-swagger-ui,採用功能更加豐富的swagger-bootstrap-ui
1. 為什麼要使用swagger-bootstrap-ui?
上一篇部落格(API管理-基於SpringBoot專案整合swagger實現介面文件自動生成)中我已經提到過使用springfox-swagger-ui的部分問題,上下結構的介面層次不利於介面的檢視、無法支援離線下載成pdf或word或html等,而swagger-bootstrap-ui的出現把這些問題都解決了並且還擴充套件了部分實用新功能,比如:新增介面頁面許可權功能..
swagger-bootstrap-ui 對比springfox-swagger-ui原生ui有哪些優點:
1. 支援介面pdf和word和markdwon方式對介面文件進行匯出,wagger-bootstrap-ui 提供markdwon格式型別的離線文件,開發者可拷貝該內容通過其他markdown轉換工具進行轉換為html或pdf.
2. 一個專案同時支援swagger-bootstrap-ui、springfox-swagger-ui二種方式同時使用
3. 介面相比springfox-swagger-ui更友好、左右排版結構更加清晰
4. 支援search相關介面內容
5. 可進行介面版本的管理
6. 國際化
7. 支援自定義文件
8. 支援開啟生產環境,遮蔽Swagger所有資源介面
9. 可設定線上介面文件許可權控制
......
2. 使用方式
基於上一篇部落格的基礎上新增如下配置:
- 新增swagger-bootstrap-ui 增強ui pom依賴
<!-- swagger-bootstrap-ui增強ui --> <dependency> <groupId>com.github.xiaoymin</groupId> <artifactId>swagger-bootstrap-ui</artifactId> <version>1.9.4</version> </dependency>
- 在MvcConfig類中新增 registry.addResourceHandler("doc.html").addResourceLocations("classpath:/META-INF/resources/");
public void addResourceHandlers(ResourceHandlerRegistry registry) { //如果靜態檔案放到了classpath 下,就如下配置。 registry.addResourceHandler("/static/**").addResourceLocations("classpath:/static/"); /*放行swagger*/ registry.addResourceHandler("swagger-ui.html") .addResourceLocations("classpath:/META-INF/resources/"); registry.addResourceHandler("doc.html").addResourceLocations("classpath:/META-INF/resources/"); registry.addResourceHandler("/webjars/**") .addResourceLocations("classpath:/META-INF/resources/webjars/"); super.addResourceHandlers(registry); }
- 啟動專案、訪問地址、檢視介面資訊:http://localhost:8080/doc.html
- 效果圖
3. 如果將markdown(.md)檔案快速匯出成html或word檔案
swagger-bootstrap-ui 提供markdwon格式型別的離線文件,開發者可拷貝該內容通過其他markdown轉換工具進行轉換為html或pdf.
pandoc安裝參考部落格:https://blog.csdn.net/xc_zhou/article/details/81009893 , https://www.jianshu.com/p/52cbee87a45a
pandoc下載地址:https://github.com/jgm/pandoc/releases/tag/2.2
1》按照md->HTML->PDF的路徑轉。於是先把md轉為HTML,HTML的樣式倒是挺美觀,然後在瀏覽器中使用瀏覽器的列印功能把HTML轉為PDF。
2》md->docx->PDF(推薦)
pandoc -s test.md -o test.docx
pandoc -f markdown -t html -o test.html readme.md
html生成後可以自定樣式檔案,使文件更好看
4. 總結
swagger-bootstrap-ui 對比springfox-swagger-ui原生ui,比原生ui強大很多,配置使用方式二者一致,swagger掃描到的資料資訊是不變的,相當於換了一個管理端頁面,呈現出不一樣的管理方式,更加友好,推薦使用swagger-bootstrap-ui,詳細的功能請參考碼雲開源專案:swagge