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);
}

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

(adsbygoogle = window.adsbygoogle || []).push({});

本文参与腾讯云自媒体分享计划,欢迎正在阅读的你也加入,一起分享。

发表于

我来说两句

0 条评论
登录 后参与评论

扫码关注云+社区

领取腾讯云代金券