怎么将swagger API导出为HTML或者PDF
文章目录
- 将swagger API导出为HTML或者PDF
- 什么是Asciidoc
- swagger2markup-maven-plugin
- asciidoctor-maven-plugin
- 使用命令行
- PDF的中文展示
- PDF中文主题在maven中的使用
将swagger API导出为HTML或者PDF
现在有很多项目都是使用的swagger,将API直接写在swagger文档中,使用起来非常方便,并且支持在线调试。但是它不方便对外提供,这里我们找到了一种方法,可以方便的将swagger API导出为HTML或者PDF。
主要使用maven的两个插件:
- swagger2markup-maven-plugin
- asciidoctor-maven-plugin
下面我们会详细讲解怎么使用他们和可能会遇到的问题。
什么是Asciidoc
AsciiDoc是一种文本文档格式,用于编写笔记,文档,文章,书籍,电子书,幻灯片,网页,手册页和博客。 AsciiDoc文件可以转换为多种格式,包括HTML,PDF,EPUB,手册页。
AsciiDoc是高度可配置的:AsciiDoc源文件语法和后端输出标记(可以是几乎任何类型的SGML / XML标记)都可以由用户自定义和扩展。
AsciiDoc是免费软件,并根据GNU通用公共许可证版本2(GPLv2)的条款获得许可。
AsciiDoc,它的设计初衷就是为了解决写书规模的问题,并且是 O’Reilly 的在线出版平台 Atlas 的推荐语言。
swagger2markup-maven-plugin
swagger2markup-maven-plugin这个插件可以将swagger的API转换为ASCIIDOC或者MARKDOWN和CONFLUENCE_MARKUP。这里我们选择转换为ASCIIDOC。
在build中加入如下代码:
<plugin><groupId>io.github.swagger2markup</groupId><artifactId>swagger2markup-maven-plugin</artifactId><version>1.3.7</version><configuration><!--此处端口一定要是当前项目启动所用的端口--><swaggerInput>http://localhost:7667/v2/api-docs</swaggerInput><outputDir>target/docs/asciidoc/generated</outputDir><config><!-- 除了ASCIIDOC之外,还有MARKDOWN和CONFLUENCE_MARKUP可选 --><swagger2markup.markupLanguage>ASCIIDOC</swagger2markup.markupLanguage></config></configuration></plugin>
版本我们用的是最新的1.3.7.
target/docs/asciidoc/generated 是生成的ASCIIDOC的目标地址,我们会在后面将其转换为HTML或者PDF。
运行下面命令生成asciidoc:
mvn swagger2markup:convertSwagger2markup
asciidoctor-maven-plugin
有了asciidoc,我们使用asciidoctor-maven-plugin将其转换为HTML和PDF。
Asciidoctor是一种快速,开放源代码的文本处理器和发布工具链,用于将AsciiDoc内容转换为HTML5,DocBook,PDF和其他格式。 Asciidoctor用Ruby编写,可在所有主要操作系统上运行。
Asciidoctor提供了一个asciidoctor-maven-plugin,可以方便的在maven环境使用。其配置如下:
<plugins><plugin><groupId>org.asciidoctor</groupId><artifactId>asciidoctor-maven-plugin</artifactId><version>2.0.0-RC.1</version><dependencies><dependency><groupId>org.asciidoctor</groupId><artifactId>asciidoctorj-pdf</artifactId><version>1.5.0-alpha.18</version></dependency><!-- Comment this section to use the default jruby artifact provided by the plugin --><dependency><groupId>org.jruby</groupId><artifactId>jruby-complete</artifactId><version>9.2.7.0</version></dependency><!-- Comment this section to use the default AsciidoctorJ artifact provided by the plugin --><dependency><groupId>org.asciidoctor</groupId><artifactId>asciidoctorj</artifactId><version>2.0.0</version></dependency></dependencies><configuration><sourceDirectory>src/docs/asciidoc</sourceDirectory><!-- Attributes common to all output formats --><attributes><sourcedir>target/docs/asciidoc/generated</sourcedir></attributes></configuration><executions><execution><id>generate-pdf-doc</id><phase>generate-resources</phase><goals><goal>process-asciidoc</goal></goals><configuration><backend>pdf</backend><!-- Since 1.5.0-alpha.9 PDF back-end can use 'rouge' as well as 'coderay'for source highlighting --><!-- Due to a known issue on windows, it is recommended to use 'coderay' until an new version of 'rouge' is released.--><sourceHighlighter>coderay</sourceHighlighter><attributes><icons>font</icons><pagenums/><toc/><idprefix/><idseparator>-</idseparator></attributes></configuration></execution></executions></plugin>
运行下面命令生成HTML和PDF:
mvn generate-resources
使用命令行
上面讲到了,Asciidoctor是基于ruby的,有了asciidoc之后,我们也可以直接使用Asciidoctor的命令行来进行转换。步骤如下:
安装rvm:rvm是一个ruby的版本管理工具,方便使用。当然你也可以使用系统原生的ruby。ruby的版本必须在2.3以上。
安装asciidoctor-pdf:
gem install asciidoctor-pdf --pre
转换pdf:
asciidoctor -r asciidoctor-pdf -b pdf basic-example.adoc
PDF的中文展示
Asciidoctor可以处理全范围的UTF-8字符的字符集。这意味着你可以写你的文档中的任何语言,使用UTF-8编码的文件,并期望Asciidoctor到文本正确转换。但是,您可能会注意到PDF中缺少某些语言的某些字符,例如中文。
如果您使用非拉丁语书写,则需要使用专门的主题来提供必要的字体。例如,以从写在CJK语言文档的PDF如中国,你需要使用一个CJK主题。您可以通过安装asciidoctor-pdf-cjk-kai_gen_gothic gem获得这样的主题。
采用专用的主题,是因为PDF需要你自己提供字体来为所有字符提供字形。没有一种字体可以支持世界上所有的语言(尽管像Noto Serif之类的语言肯定会比较接近)。
因此,我们采取的策略是针对每个语言家族(例如CJK)创建单独的专用主题。当然,您可以自由地遵循这种模式,并使用选择的字体来创建自己的主题。
怎么创建主题这里就不详细讲解了,有兴趣的小伙伴可以自行查阅有关资料。
如何安装:
gem install asciidoctor-pdf-cjk-kai_gen_gothic
下载字体:
asciidoctor-pdf-cjk-kai_gen_gothic-install
这个主题支持以下几种字体:
- KaiGenGothicCN
- KaiGenGothicJP
- KaiGenGothicKR
- KaiGenGothicTW
使用下面的命令来转换PDF:
asciidoctor-pdf -r asciidoctor-pdf-cjk-kai_gen_gothic -a pdf-style=THEME doc.asc
这里我遇到了一个问题,如果字体选择KaiGenGothicCN, 那么会在运行时候报错:
undefined method `strip_extended' for nil:NilClassUse --trace for backtrace
详细查看–trace,会发现报错的是ttfunk/table/name.rb:
@postscript_name = @strings[6].first.strip_extended
从字体中获取到的@strings[6]是空。 那么怎么办呢?
很简单,使用KaiGenGothicTW字体即可。
PDF中文主题在maven中的使用
那么有了命令行,我们怎么在maven中使用呢?
请使用如下的XML配置:
<execution><id>output-pdf</id><phase>generate-resources</phase><goals><goal>process-asciidoc</goal></goals><configuration><backend>pdf</backend><outputDirectory>target/docs/asciidoc/pdf</outputDirectory><attributes><pdf-stylesdir>/Library/Ruby/Gems/2.3.0/gems/asciidoctor-pdf-cjk-kai_gen_gothic-0.1.1/data/themes</pdf-stylesdir><pdf-style>KaiGenGothicTW</pdf-style><pdf-fontsdir>/Library/Ruby/Gems/2.3.0/gems/asciidoctor-pdf-cjk-kai_gen_gothic-0.1.1/data/fonts</pdf-fontsdir><icons>font</icons><pagenums/><toc/><idprefix/><idseparator>-</idseparator></attributes></configuration></execution>
请关注如下几个字段:
pdf-stylesdir:你安装的中文主题的目录
pdf-style:中文主题的名称
pdf-fontsdir: 中文主题字体的名称。
好了,本文讲到这里,有疑问的小伙伴可以发邮件或者留言提问。谢谢。
更多教程请参考 flydean的博客
怎么将swagger API导出为HTML或者PDF相关推荐
- 集成Swagger(API)---SpringBoot
集成Swagger(API) 学习目标: 了解Swagger的概念及作用 掌握在项目中集成Swagger自动生成API文档 Swagger简介 前后端分离 前端 -> 前端控制层.视图层 后端 ...
- swagger api文档_带有Swagger的Spring Rest API –创建文档
swagger api文档 使REST API易于使用的真正关键是好的文档. 但是,即使您的文档做得很好,您也需要设置公司流程的权利以正确,及时地发布它. 确保利益相关者按时收到是一回事,但是您也要负 ...
- swagger api文档_带有Swagger的Spring Rest API –公开文档
swagger api文档 创建API文档后,将其提供给涉众很重要. 在理想情况下,此发布的文档将足够灵活以解决任何最后的更改,并且易于分发(就成本以及完成此操作所需的时间而言). 为了使之成为可能, ...
- swagger 扫描java文档_推荐一款在运行时通过javadoc生成Swagger API文档的库
介绍 一般,我们使用Springfox生成swagger api文档,但Springfox不支持从javadoc中生成,只能通过注解的方式标注文档. 这样,当共享一些POJO类时,为了同时生成java ...
- swagger easyExcel导出Excel文件打不开,文件损坏
alibaba/easyexcel文件导出 swagger easyExcel导出Excel文件打不开,文件损坏 文件下载打不开,将文件输出到本地发现可以打开,而且swagger下载的文件大小比本地文 ...
- swagger接口导出excel文件打不开
swagger接口导出excel文件打不开: 接口添加produces="application/octet-stream" @ApiOperation(value = " ...
- Swagger(Api接口管理)
Swagger(Api管理) 主要应用于前后端分离的项目,实时更新最新API,降低集成风险. RestFul Api文档在线自动生成工具=>Api文档与Api定义同步更新 直接运行,可以在线测试 ...
- 通用的web系统数据导出功能设计实现(导出excel2003/2007 word pdf zip等)
前言 我们在做web系统中,导出也是很常用的一个功能,如果每一个数据列表都要对应写一个导出的方法不太现实.现在就想设计一个共通的功能来实现这个导出. 需求分析 在开始之前我们先要明白我们要实现怎样一个 ...
- android webview将网页内容导出为图片和PDF方法
项目需求中需要把webview的网页内容导出为图片和PDF,方法如下 导出为PDF 注意: 该方法只能在API 19+可以使用 代码如下: public void printPDF() {if (Bu ...
最新文章
- 又一个智商税产品“路由器防辐射笼”,信号都没了,还能火爆全网...
- 输入输出(Input and Output)
- java coin介绍_代码示例中的Java 7:Project Coin
- windows执行oracle脚本,Windows下通过计划任务执行数据库备份脚本
- Linux 常见问题 1000 个详细解答
- 计算机专业学生前端该怎么自学?
- 均值滤波python实现_python手写均值滤波
- 毕设题目:Matlab电子琴
- 移远EC20模组网口SGMII通讯调试以及FC20wifi通讯调试
- Flash Player离线安装包下载指南
- 使用idea格式化xml中的SQL
- 曼切斯特编码波特率和比特率的关系
- SpringBoot整合JdbcTemplate(五)
- 无线局域网安全(三)————CCMP加密
- 哄女朋友玩的c语言编程,哄女朋友开心的小套路 逗女朋友开心的话套路
- 你知道Base64编码的图片吗
- 线上知识付费潮流中的青年人:寻找消费与求知的平衡点
- 认识和使用热插拔的正确姿势-续
- 国密SSL协议之双证书体系
- java做百度语言识别_java实现百度云文字识别接口代码