现在有很多项目都是使用的swagger,将API直接写在swagger文档中,使用起来非常方便,并且支持在线调试。但是它不方便对外提供,这里我们找到了一种方法,可以方便的将swagger API导出为HTML或者PDF。
主要使用maven的两个插件:
下面我们会详细讲解怎么使用他们和可能会遇到的问题。
AsciiDoc是一种文本文档格式,用于编写笔记,文档,文章,书籍,电子书,幻灯片,网页,手册页和博客。 AsciiDoc文件可以转换为多种格式,包括HTML,PDF,EPUB,手册页。
AsciiDoc是高度可配置的:AsciiDoc源文件语法和后端输出标记(可以是几乎任何类型的SGML / XML标记)都可以由用户自定义和扩展。
AsciiDoc是免费软件,并根据GNU通用公共许可证版本2(GPLv2)的条款获得许可。
AsciiDoc,它的设计初衷就是为了解决写书规模的问题,并且是 O’Reilly 的在线出版平台 Atlas 的推荐语言。
swagger2markup-maven-plugin这个插件可以将swagger的API转换为ASCIIDOC或者MARKDOWN和CONFLUENCE_MARKUP。这里我们选择转换为ASCIIDOC。
在build中加入如下代码:
<plugin>
<groupId>io.github.swagger2markupgroupId>
<artifactId>swagger2markup-maven-pluginartifactId>
<version>1.3.7version>
<configuration>
<swaggerInput>http://localhost:7667/v2/api-docsswaggerInput>
<outputDir>target/docs/asciidoc/generatedoutputDir>
<config>
<swagger2markup.markupLanguage>ASCIIDOCswagger2markup.markupLanguage>
config>
configuration>
plugin>
版本我们用的是最新的1.3.7.
target/docs/asciidoc/generated 是生成的ASCIIDOC的目标地址,我们会在后面将其转换为HTML或者PDF。
运行下面命令生成asciidoc:
mvn swagger2markup:convertSwagger2markup
有了asciidoc,我们使用asciidoctor-maven-plugin将其转换为HTML和PDF。
Asciidoctor是一种快速,开放源代码的文本处理器和发布工具链,用于将AsciiDoc内容转换为HTML5,DocBook,PDF和其他格式。 Asciidoctor用Ruby编写,可在所有主要操作系统上运行。
Asciidoctor提供了一个asciidoctor-maven-plugin,可以方便的在maven环境使用。其配置如下:
<plugins>
<plugin>
<groupId>org.asciidoctorgroupId>
<artifactId>asciidoctor-maven-pluginartifactId>
<version>2.0.0-RC.1version>
<dependencies>
<dependency>
<groupId>org.asciidoctorgroupId>
<artifactId>asciidoctorj-pdfartifactId>
<version>1.5.0-alpha.18version>
dependency>
<dependency>
<groupId>org.jrubygroupId>
<artifactId>jruby-completeartifactId>
<version>9.2.7.0version>
dependency>
<dependency>
<groupId>org.asciidoctorgroupId>
<artifactId>asciidoctorjartifactId>
<version>2.0.0version>
dependency>
dependencies>
<configuration>
<sourceDirectory>src/docs/asciidocsourceDirectory>
<attributes>
<sourcedir>target/docs/asciidoc/generatedsourcedir>
attributes>
configuration>
<executions>
<execution>
<id>generate-pdf-docid>
<phase>generate-resourcesphase>
<goals>
<goal>process-asciidocgoal>
goals>
<configuration>
<backend>pdfbackend>
<sourceHighlighter>coderaysourceHighlighter>
<attributes>
<icons>fonticons>
<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
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
这个主题支持以下几种字体:
使用下面的命令来转换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字体即可。
那么有了命令行,我们怎么在maven中使用呢?
请使用如下的XML配置:
<execution>
<id>output-pdfid>
<phase>generate-resourcesphase>
<goals>
<goal>process-asciidocgoal>
goals>
<configuration>
<backend>pdfbackend>
<outputDirectory>target/docs/asciidoc/pdfoutputDirectory>
<attributes>
<pdf-stylesdir>/Library/Ruby/Gems/2.3.0/gems/asciidoctor-pdf-cjk-kai_gen_gothic-0.1.1/data/themespdf-stylesdir>
<pdf-style>KaiGenGothicTWpdf-style>
<pdf-fontsdir>/Library/Ruby/Gems/2.3.0/gems/asciidoctor-pdf-cjk-kai_gen_gothic-0.1.1/data/fontspdf-fontsdir>
<icons>fonticons>
<pagenums/>
<toc/>
<idprefix/>
<idseparator>-idseparator>
attributes>
configuration>
execution>
请关注如下几个字段:
pdf-stylesdir:你安装的中文主题的目录
pdf-style:中文主题的名称
pdf-fontsdir: 中文主题字体的名称。
好了,本文讲到这里,有疑问的小伙伴可以发邮件或者留言提问。谢谢。
更多教程请参考 flydean的博客