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,详细的功能请参考码云开源项目:swagger-bootstrap-ui。