将swagger API导出为HTML或者PDF

现在有很多项目都是使用的swagger,将API直接写在swagger文档中,使用起来非常方便,并且支持在线调试。但是它不方便对外提供,这里我们找到了一种方法,可以方便的将swagger API导出为HTML或者PDF。

主要使用maven的两个插件:

  1. swagger2markup-maven-plugin
  2. 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的命令行来进行转换。步骤如下:

  1. 安装rvm:rvm是一个ruby的版本管理工具,方便使用。当然你也可以使用系统原生的ruby。ruby的版本必须在2.3以上。

  2. 安装asciidoctor-pdf:

    gem install asciidoctor-pdf --pre

  3. 转换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的更多相关文章

  1. 添加swagger api文档到node服务

    swagger,一款api测试工具,详细介绍参考官网:http://swagger.io/ ,这里主要记录下怎么将swagger api应用到我们的node服务中: 1.任意新建node api项目, ...

  2. Swagger API接口管理

    介绍         Swagger API框架,用于管理项目中API接口,属当前最流行的API接口管理工具. Swagger功能强大,UI界面漂亮,支持在线测试等!         Swagger包 ...

  3. xadmin引入drf-yasg生成Swagger API文档

    一.安装drf-yasg: 由于django-rest-swagger已经废弃了 所以引入了drf-yasg pip install drf-yasg 安装install drf-yasg库 http ...

  4. NET 5.0 Swagger API 自动生成MarkDown文档

    目录 1.SwaggerDoc引用 主要接口 接口实现 2.Startup配置 注册SwaggerDoc服务 注册Swagger服务 引用Swagger中间件 3.生成MarkDown 4.生成示例 ...

  5. swagger api 转graphql npm 包试用

    graphql 比较方便的进行api 的查询,操作,swagger 是一个方便的open api 描述标准,当前我们有比较多的 restapi 但是转换为graphql 是有成本的,还好swagger ...

  6. swagger & api & swagger ui

    swagger & api swagger ui # run server $ swagger project start api-app # call api $ curl http://1 ...

  7. Swagger API文档集中化注册管理

    接口文档是前后端开发对接时很重要的一个组件.手动编写接口文档既费时,又存在文档不能随代码及时更新的问题,因此产生了像swagger这样的自动生成接口文档的框架.swagger文档一般是随项目代码生成与 ...

  8. restful swagger api java go

    rest框架使用swagger api,接口越来越多后性能会很差,如何优化? - 知乎https://www.zhihu.com/question/59349319 golang restful 框架 ...

  9. Swagger API文档

    Swagger API文档集中化注册管理   接口文档是前后端开发对接时很重要的一个组件.手动编写接口文档既费时,又存在文档不能随代码及时更新的问题,因此产生了像swagger这样的自动生成接口文档的 ...

随机推荐

  1. 2019NYIST计科第七次周赛总结

    2019NYIST计科第七次周赛总结 文章目录 2019NYIST计科第七次周赛总结 [秤取物体重量( 二进制枚举法)](https://blog.csdn.net/qq_34261446/artic ...

  2. Java 添加、读取和删除 Excel 批注

    批注是一种富文本注释,常用于为指定的Excel单元格添加提示或附加信息. Free Spire.XLS for Java 为开发人员免费提供了在Java应用程序中对Excel文件添加和操作批注的功能. ...

  3. 【tensorflow2.0】AutoGraph的机制原理

    有三种计算图的构建方式:静态计算图,动态计算图,以及Autograph. TensorFlow 2.0主要使用的是动态计算图和Autograph. 动态计算图易于调试,编码效率较高,但执行效率偏低. ...

  4. 配置附加权限和LDAP

     配置附加权限和LDAP 补充:调整root的权限为rwx(读,写,执行) 步骤:采用数值形式将目录/root的权限调整为rwx------ 1)查看原来的权限 [root@svr7~]#ls -ld ...

  5. SSAS 第一篇:多维数据分析基础

    多维数据分析是指按照多个维度(即多个角度)对数据进行观察和分析,多维的分析操作是指通过对多维形式组织起来的数据进行切片 .切块.聚合.钻取 .旋转等分析操作,以求剖析数据,使用户能够从多种维度.多个侧 ...

  6. Java Array数组使用详解

    本文主要讲解java中array数组使用,包含堆.栈内存分配及区别 1.动态初始化 package myArray; /* * 堆:存储的是new出来的东西,实体,对象 * A 每个对象都有地址值 * ...

  7. String 对象-->replace() 方法

    1.定义和用法 replace() 方法用于字符串替换 语法: string.replace(searchvalue,newvalue) 参数: searchvalue:被替换的字符串 newvalu ...

  8. Linq 学习——将List集合作为筛选条件查询数据

    例: A表是一个List集合,B表也是一个List集合 .A与B有一个共同的字段 RecognitionCarCode B表通过RecognitionCarCode去重后拿到两个值{'1','2'}记 ...

  9. defer使用小结

    defer 前言 defer的定义 defer执行的规则 为什么需要defer defer进阶 作为匿名函数 作为函数参数 defer命令执行的时机 defer配合recover 总结 参考 defe ...

  10. Java的多线程编程模型5--从AtomicInteger开始

    Java的多线程编程模型5--从AtomicInteger开始 2011-06-23 20:50 11393人阅读 评论(9) 收藏 举报 java多线程编程jniinteger测试 AtomicIn ...