使用spring boot + swagger2markup + springFox + asciidoctor自动生成HTML、PDF接口文档,并解决中文显示为空白问题

做后端开发,自然离不开接口文档,接口文档不仅方便后端开发人员之间查看,更是前端人员必要的文档,也有可能提供给第三方来调用我们的接口。但是,写接口文档太费时间,而且如果没有确定好格式,每个人写的接口文档可能各不相同,看起来就会很混乱。

好在swagger出现了,如果你的spring boot项目集成了swagger,而且接口和入参出参实体类加上了swagger相关的注解(参考最终demo中的controllermodel),那么,就可以通过http://ip:port/swagger-ui.html(ipport换成自己配置的)来访问在线的接口,在此页面也可以直接测试接口。对spring bootswagger不了解的建议先学习一下,近年来很火,使用起来也确实方便。但是我们肯定不会满足在线访问就可以了的,有时候会需要离线的接口文档,于是就有了swagger2markupspringFoxasciidoctor几个插件来帮助我们生成离线的HTMLPDF格式的文档。

关于使用swagger生成HTML或者PDF的原理,可以参考这篇文章:使用 SpringFox、Swagger2Markup、Spring-Restdoc和 Maven 构建 RESTful API文档。

首先是从spring-swagger2markup-demo下载了demo,这个demo已经能够生成HTMLPDF文档了,但是对中文支持不好,中文大部分会显示为空白。如果你的接口文档是全英文的,那么就用这个就可以了。关于这个demo对中文支持不好,查了很多资料,应该是字体和主题的原因,所以参考了很多资料,结合当前这个demo,做出了最终的能很好支持中文的demo,最终demo地址:swagger2pdf。

生成的文档存放的目录:当前项目的target\asciidoc\htmltarget\asciidoc\pdf分别存放着HTML文档PDF文档

关于接口和入参出参实体类中用到的swagger注解,可以参考这篇博客:swagger2常用注解说明。

最终生成的HTML文档PDF文档效果图:

html.png

pdf.png

由于参考了很多资料都没有成功,只记录了最后成功的链接,没有记录下其他的链接,如果您觉得其中有参考您的部分,可以留言留下您的地址,我会加到参考的链接里的。

主要参考:

  • https://github.com/Swagger2Markup/spring-swagger2markup-demo
  • https://blog.csdn.net/lihuaijun/article/details/79727863
  • https://github.com/woshihoujinxin/swagger-gendoc

你可能感兴趣的:(使用spring boot + swagger2markup + springFox + asciidoctor自动生成HTML、PDF接口文档,并解决中文显示为空白问题)