怎么将swagger API导出为HTML或者PDF
文章目录
将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:NilClass
Use --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文档到node服务
swagger,一款api测试工具,详细介绍参考官网:http://swagger.io/ ,这里主要记录下怎么将swagger api应用到我们的node服务中: 1.任意新建node api项目, ...
- Swagger API接口管理
介绍 Swagger API框架,用于管理项目中API接口,属当前最流行的API接口管理工具. Swagger功能强大,UI界面漂亮,支持在线测试等! Swagger包 ...
- xadmin引入drf-yasg生成Swagger API文档
一.安装drf-yasg: 由于django-rest-swagger已经废弃了 所以引入了drf-yasg pip install drf-yasg 安装install drf-yasg库 http ...
- NET 5.0 Swagger API 自动生成MarkDown文档
目录 1.SwaggerDoc引用 主要接口 接口实现 2.Startup配置 注册SwaggerDoc服务 注册Swagger服务 引用Swagger中间件 3.生成MarkDown 4.生成示例 ...
- swagger api 转graphql npm 包试用
graphql 比较方便的进行api 的查询,操作,swagger 是一个方便的open api 描述标准,当前我们有比较多的 restapi 但是转换为graphql 是有成本的,还好swagger ...
- swagger & api & swagger ui
swagger & api swagger ui # run server $ swagger project start api-app # call api $ curl http://1 ...
- Swagger API文档集中化注册管理
接口文档是前后端开发对接时很重要的一个组件.手动编写接口文档既费时,又存在文档不能随代码及时更新的问题,因此产生了像swagger这样的自动生成接口文档的框架.swagger文档一般是随项目代码生成与 ...
- restful swagger api java go
rest框架使用swagger api,接口越来越多后性能会很差,如何优化? - 知乎https://www.zhihu.com/question/59349319 golang restful 框架 ...
- Swagger API文档
Swagger API文档集中化注册管理 接口文档是前后端开发对接时很重要的一个组件.手动编写接口文档既费时,又存在文档不能随代码及时更新的问题,因此产生了像swagger这样的自动生成接口文档的 ...
随机推荐
- 发现钉钉打卡定位算法的一个bug
最近公司取消了指纹打卡,改用钉钉打卡. 天天用这个打卡上班,经常忘记,困扰. 最烦的是好几次明明人在办公室,打卡地址显示在10分钟前的位置,定位失败,不得不重新打卡. 经历过几次定位失败后,我就琢磨起 ...
- Blazor入门笔记(5)-数据绑定
1.环境 VS2019 16.5.1 .NET Core SDK 3.1.200 Blazor WebAssembly Templates 3.2.0-preview2.20160.5 2.默认绑定 ...
- 新建jsp文件,The superclass "javax.servlet.http.HttpServlet" was not found on the Java Build Path错误解决方法
新建一个jsp文件后,有一个错误,The superclass "javax.servlet.http.HttpServlet" was not found on the Java ...
- es6声明一个类
js语言的传统方式是通过定义构造函数,生成心得对象.是一种基于原型的面向对象系统.在es6中增加了class类的概念,可以使用class关键字来声明一个类.之后用这个类来实例化对象. 构造函数示例 c ...
- SpringMVC(五):JSON
本文是按照狂神说的教学视频学习的笔记,强力推荐,教学深入浅出一遍就懂!b站搜索狂神说或点击下面链接 https://space.bilibili.com/95256449?spm_id_from=33 ...
- Git常用命令(二)
git clone + URL 获取该项目源代码 $ git log 回顾提交历史 $ git log -p -(数字) 用来显示每次提交的内容差异+(数字)表示看最近几条 $ git log --s ...
- 30.6 HashMap的使用
/* * * 使用HashMap存储数据并遍历(字符串作为key) * *使用HashMap存储数据并遍历(自定义对象作为key) */ 字符串做key和Map的使用一样,重点介绍自定义对象作为key ...
- django创建app
前几天,
- Problem L. World Cup
题目大意:有A,B,C,D四个队伍,两两之间有一个比赛,假如A和B比赛,如果平局,各加一分,如果说A胜,给A加3分,不给B加分,B胜同理 给出A,B,C,D,的得分,判断形成这种局面有多少种方式. 思 ...
- 树莓派4b 上手三板斧
树莓派4b 上手三板斧 1.无屏幕和网线连接准备 windows / mac 电脑下载安装Notepad++ 新建文件并保存为ssh(该文件为空文件) 新建文件wpa_supplicant.conf ...