持原创，共同进步！请关注我，后续分享更精彩!

背景

程序员日常工作中，经常会用Markdown编写一些技术文档。但在一某些场合，直接Markdown文件交互会不太适合，毕竟一些阅读受众可能是业务或产品人员，不具有相应技术背景。这时就需要把Markdown转换为更通用可读的pdf文件格式。

本文向大家推荐一款好用的在线Markdown转pdf的工具--md2pdf，还提供水印打印功能。

在线工具

http://open.rongcard.com/md2pdf

案例

本文将java后端api的接口文档，通过swagger工具导出为Markdown格式，并使用在线md2pdf转换成pdf文档，提供给外部合作人员。

注：后端项目中集成swagger插件可点击文章(swagger2和mybatis-generator集成Api接口文档实践 )

使用

启动集成swagger的java后端项目，浏览器访问http://{ip:port}/doc.html

swagger界面点击：文档管理 - -> 离线文档(MD) - -> 拷贝文档

浏览器打开Markdown转pdf在线工具：http://open.rongcard.com/md2pdf

点击"导出"按钮，开始下载。

查看下载文件，相应Markdown已转换为pdf文件内容。

小结

文章向大家分享了一款在线Markdown转pdf的工具使用。并演示了java后端api离线导出pdf格式的方法。

希望对大家在项目中有所帮助和参考。若有更好的工具推荐，欢迎留言讨论。

网上有很多《使用swagger2构建API文档》的文章，swagger2文档是一个在线文档，需要使用HTTP访问。但是在我们日常使用swagger接口文档的时候，有的时候需要接口文档离线访问，如将文档导出为html、markdown格式。又或者我们不希望应用系统与swagger接口文档使用同一个服务，而是导出HTML之后单独部署，这样做保证了对接口文档的访问不影响业务系统，也一定程度提高了接口文档的安全性。核心的实现过程就是：

• 在swagger2接口文档所在的应用内，利用swagger2markup将接口文档导出为adoc文件，也可以导出markdown文件。
• 然后将adoc文件转换为静态的html格式，可以将html发布到nginx或者其他的web应用容器，提供访问（本文不会讲html静态部署，只讲HTML导出)。

注意：adoc是一种文件格式，不是我的笔误。不是doc文件也不是docx文件。

一、maven依赖类库

在已经集成了swagger2的应用内，通过maven坐标引入相关依赖类库,pom.xml代码如下：

<dependency>
 <groupId>io.github.swagger2markup</groupId>
 <artifactId>swagger2markup</artifactId>
 <version>1.3.1</version>
</dependency>
<dependency>
 <groupId>io.swagger</groupId>
 <artifactId>swagger-core</artifactId>
 <version>1.5.16</version>
</dependency>
<dependency>
 <groupId>io.swagger</groupId>
 <artifactId>swagger-models</artifactId>
 <version>1.5.16</version>
</dependency>

swagger2markup用于将swagger2在线接口文档导出为html,markdown,adoc等格式文档，用于静态部署或离线阅读。其中第一个maven坐标是必须的。后两个maven坐标，当你在执行后面的代码过程中报下图中的ERROR，或者有的类无法import的时候使用。

产生异常的原因已经有人在github的issues上给出解释了：当你使用swagger-core版本大于等于1.5.11,并且swagger-models版本小于1.5.11就会有异常发生。所以我们显式的引入这两个jar，替换掉swagger2默认引入的这两个jar。

二、生成adoc格式文件

下面的代码是通过编码方式实现的生成adoc格式文件的方式

@RunWith(SpringRunner.class)
@SpringBootTest(webEnvironment=SpringBootTest.WebEnvironment.DEFINED_PORT)
public class DemoApplicationTests {
 @Test
 public void generateAsciiDocs() throws Exception {
 // 输出Ascii格式
 Swagger2MarkupConfig config=new Swagger2MarkupConfigBuilder()
 .withMarkupLanguage(MarkupLanguage.ASCIIDOC) //设置生成格式
 .withOutputLanguage(Language.ZH) //设置语言中文还是其他语言
 .withPathsGroupedBy(GroupBy.TAGS)
 .withGeneratedExamples()
 .withoutInlineSchema()
 .build();

 Swagger2MarkupConverter.from(new URL("http://localhost:8888/v2/api-docs"))
 .withConfig(config)
 .build()
 .toFile(Paths.get("src/main/resources/docs/asciidoc"));
 }
}

• 使用RunWith注解和SpringBootTest注解，启动应用服务容器。 SpringBootTest.WebEnvironment.DEFINED_PORT表示使用application.yml定义的端口，而不是随机使用一个端口进行测试，这很重要。
• Swagger2MarkupConfig 是输出文件的配置，如文件的格式和文件中的自然语言等
• Swagger2MarkupConverter的from表示哪一个HTTP服务作为资源导出的源头(JSON格式)，可以自己访问试一下这个链接。8888是我的服务端口，需要根据你自己的应用配置修改。
• toFile表示将导出文件存放的位置，不用加后缀名。也可以使用toFolder表示文件导出存放的路径。二者区别在于使用toFolder导出为文件目录下按标签TAGS分类的多个文件，使用toFile是导出一个文件（toFolder多个文件的合集）。

@Test
public void generateMarkdownDocsToFile() throws Exception {
 // 输出Markdown到单文件
 Swagger2MarkupConfig config=new Swagger2MarkupConfigBuilder()
 .withMarkupLanguage(MarkupLanguage.MARKDOWN)
 .withOutputLanguage(Language.ZH)
 .withPathsGroupedBy(GroupBy.TAGS)
 .withGeneratedExamples()
 .withoutInlineSchema()
 .build();

 Swagger2MarkupConverter.from(new URL("http://localhost:8888/v2/api-docs"))
 .withConfig(config)
 .build()
 .toFile(Paths.get("src/main/resources/docs/markdown"));
}

上面的这一段代码是生成markdown格式接口文件的代码。执行上面的2段单元测试代码，就可以生产对应格式的接口文件。

还有一种方式是通过maven插件的方式，生成adoc和markdown格式的接口文件。笔者不常使用这种方式，没有使用代码生成的方式配置灵活，很多配置都放到pom.xml感觉很臃肿。但还是介绍一下,首先配置maven插件swagger2markup-maven-plugin。

<plugin>
 <groupId>io.github.swagger2markup</groupId>
 <artifactId>swagger2markup-maven-plugin</artifactId>
 <version>1.3.1</version>
 <configuration>
 <swaggerInput>http://localhost:8888/v2/api-docs</swaggerInput><!---swagger-api-json路径-->
 <outputDir>src/main/resources/docs/asciidoc</outputDir><!---生成路径-->
 <config>
 <swagger2markup.markupLanguage>ASCIIDOC</swagger2markup.markupLanguage><!--生成格式-->
 </config>
 </configuration>
</plugin>

然后运行插件swagger2markup就可以了，如下图：

三、通过maven插件生成HTML文档

<plugin>
 <groupId>org.asciidoctor</groupId>
 <artifactId>asciidoctor-maven-plugin</artifactId>
 <version>1.5.6</version>
 <configuration>
 <!--asciidoc文件目录-->
 <sourceDirectory>src/main/resources/docs</sourceDirectory>
 <!---生成html的路径-->
 <outputDirectory>src/main/resources/html</outputDirectory>
 <backend>html</backend>
 <sourceHighlighter>coderay</sourceHighlighter>
 <attributes>
 <!--导航栏在左-->
 <toc>left</toc>
 <!--显示层级数-->
 <!--<toclevels>3</toclevels>-->
 <!--自动打数字序号-->
 <sectnums>true</sectnums>
 </attributes>
 </configuration>
</plugin>

adoc的sourceDirectory路径必须和第三小节中生成的adoc文件路径一致。然后按照下图方式运行插件。

HTMl接口文档显示的效果如下，有了HTML接口文档你想转成其他各种格式的文档就太方便了，有很多工具可以使用。这里就不一一介绍了。

者：HelloGitHub-追梦人物

在 Django博客教程（第二版）中，我们给博客内容增加了 Markdown 的支持，博客详情接口应该返回解析后的 HTML 内容。

来回顾一下 Post 模型的代码，Markdown 解析后的 HTML 保存在这几个属性中：

rich_content 是 body Markdown 内容解析后的 HTML 内容，使用了 cached_property 装饰器缓存解析后的结果，以降低多次访问的开销。body_html 属性为解析后的正文内容，toc 属性是从正文标题中提取的目录。

toc 和 body_html 这两个属性的值是我们需要序列化并在接口中返回的，那么可否像之前那样，直接在序列化器 PostRetrieveSerializer 的 Meta.fields 中添加这两个属性就行了呢？

答案是不能。之前说过，模型字段不同类型的值都需要不同的序列化字段对其进行序列化，我们之所以能直接在 Meta.fields 中指定需要序列化的字段而不需要额外的代码是因为这些字段都是直接定义在 django 的模型中的。django-rest-framework 可以根据模型中的字段的定义自动推断该使用何种类型的序列化字段，但对于这里提到的 toc、body_html 属性，django-rest-framework 就无法推断其值的类型，也就无法自动使用对应的序列化字段对其进行序列化了。不过解决方法很简单，既然 django-rest-framework 无法自动推断，那我们就人工指定该使用何种类型的序列化字段就行了。

这里需要序列化的字段值都是字符串，因此在序列化器中显示地指定需要序列化的字段以及使用的系列化字段类型就可以了：

添加完成后，访问一篇文章的详情接口，就可以看到被序列化并返回的文章目录和正文 HTML 内容了。

『讲解开源项目系列』——让对开源项目感兴趣的人不再畏惧、让开源项目的发起者不再孤单。跟着我们的文章，你会发现编程的乐趣、使用和发现参与开源项目如此简单。欢迎留言联系我们、加入我们，让更多人爱上开源、贡献开源～