持原創，共同進步！請關注我，后續分享更精彩!

背景

程序員日常工作中，經常會用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 內容了。

『講解開源項目系列』——讓對開源項目感興趣的人不再畏懼、讓開源項目的發起者不再孤單。跟著我們的文章，你會發現編程的樂趣、使用和發現參與開源項目如此簡單。歡迎留言聯系我們、加入我們，讓更多人愛上開源、貢獻開源～