整合營(yíng)銷服務(wù)商
電腦端+手機(jī)端+微信端=數(shù)據(jù)同步管理
免費(fèi)咨詢熱線：
電腦端+手機(jī)端+微信端=數(shù)據(jù)同步管理
免費(fèi)咨詢熱線：
持原創(chuàng)，共同進(jìn)步！請(qǐng)關(guān)注我，后續(xù)分享更精彩!程序員日常工作中，經(jīng)常會(huì)用Markdown編寫一些技術(shù)文檔。但在一某些場(chǎng)合，直接Markdown文件交互會(huì)不太適合，畢竟一些閱讀受眾可能是業(yè)務(wù)或產(chǎn)品人員，不具有相應(yīng)技術(shù)背景。這時(shí)就需要把Markdown轉(zhuǎn)換為更通用可讀的pdf文件格式。
本文向大家推薦一款好用的在線Markdown轉(zhuǎn)pdf的工具--md2pdf，還提供水印打印功能。
http://open.rongcard.com/md2pdf
本文將java后端api的接口文檔，通過(guò)swagger工具導(dǎo)出為Markdown格式，并使用在線md2pdf轉(zhuǎn)換成pdf文檔，提供給外部合作人員。
注：后端項(xiàng)目中集成swagger插件可點(diǎn)擊文章(swagger2和mybatis-generator集成Api接口文檔實(shí)踐 )
啟動(dòng)集成swagger的java后端項(xiàng)目，瀏覽器訪問(wèn)http://{ip:port}/doc.html
swagger界面點(diǎn)擊：文檔管理 - -> 離線文檔(MD) - -> 拷貝文檔
瀏覽器打開(kāi)Markdown轉(zhuǎn)pdf在線工具：http://open.rongcard.com/md2pdf
點(diǎn)擊"導(dǎo)出"按鈕，開(kāi)始下載。
查看下載文件，相應(yīng)Markdown已轉(zhuǎn)換為pdf文件內(nèi)容。
文章向大家分享了一款在線Markdown轉(zhuǎn)pdf的工具使用。并演示了java后端api離線導(dǎo)出pdf格式的方法。
希望對(duì)大家在項(xiàng)目中有所幫助和參考。若有更好的工具推薦，歡迎留言討論。
Swagger2文檔導(dǎo)出為HTML或markdown等格式離線閱讀
網(wǎng)上有很多《使用swagger2構(gòu)建API文檔》的文章，swagger2文檔是一個(gè)在線文檔，需要使用HTTP訪問(wèn)。但是在我們?nèi)粘Ｊ褂胹wagger接口文檔的時(shí)候，有的時(shí)候需要接口文檔離線訪問(wèn)，如將文檔導(dǎo)出為html、markdown格式。又或者我們不希望應(yīng)用系統(tǒng)與swagger接口文檔使用同一個(gè)服務(wù)，而是導(dǎo)出HTML之后單獨(dú)部署，這樣做保證了對(duì)接口文檔的訪問(wèn)不影響業(yè)務(wù)系統(tǒng)，也一定程度提高了接口文檔的安全性。核心的實(shí)現(xiàn)過(guò)程就是：
注意：adoc是一種文件格式，不是我的筆誤。不是doc文件也不是docx文件。
在已經(jīng)集成了swagger2的應(yīng)用內(nèi)，通過(guò)maven坐標(biāo)引入相關(guān)依賴類庫(kù),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在線接口文檔導(dǎo)出為html,markdown,adoc等格式文檔，用于靜態(tài)部署或離線閱讀。其中第一個(gè)maven坐標(biāo)是必須的。后兩個(gè)maven坐標(biāo)，當(dāng)你在執(zhí)行后面的代碼過(guò)程中報(bào)下圖中的ERROR，或者有的類無(wú)法import的時(shí)候使用。
swagger2markup過(guò)程可能拋出的異常
產(chǎn)生異常的原因已經(jīng)有人在github的issues上給出解釋了：當(dāng)你使用swagger-core版本大于等于1.5.11,并且swagger-models版本小于1.5.11就會(huì)有異常發(fā)生。所以我們顯式的引入這兩個(gè)jar，替換掉swagger2默認(rèn)引入的這兩個(gè)jar。
swagger2markup異常的解決方案
下面的代碼是通過(guò)編碼方式實(shí)現(xiàn)的生成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) //設(shè)置生成格式
.withOutputLanguage(Language.ZH) //設(shè)置語(yǔ)言中文還是其他語(yǔ)言
.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"));
}
}@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格式接口文件的代碼。執(zhí)行上面的2段單元測(cè)試代碼，就可以生產(chǎn)對(duì)應(yīng)格式的接口文件。
還有一種方式是通過(guò)maven插件的方式，生成adoc和markdown格式的接口文件。筆者不常使用這種方式，沒(méi)有使用代碼生成的方式配置靈活，很多配置都放到pom.xml感覺(jué)很臃腫。但還是介紹一下,首先配置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>
然后運(yùn)行插件swagger2markup就可以了，如下圖：
插件運(yùn)行方式(點(diǎn)擊可放大)
<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> <!--導(dǎo)航欄在左--> <toc>left</toc> <!--顯示層級(jí)數(shù)--> <!--<toclevels>3</toclevels>--> <!--自動(dòng)打數(shù)字序號(hào)--> <sectnums>true</sectnums> </attributes> </configuration> </plugin>
adoc的sourceDirectory路徑必須和第三小節(jié)中生成的adoc文件路徑一致。然后按照下圖方式運(yùn)行插件。
asciidoctor:process-asciidoc插件運(yùn)行
HTMl接口文檔顯示的效果如下，有了HTML接口文檔你想轉(zhuǎn)成其他各種格式的文檔就太方便了，有很多工具可以使用。這里就不一一介紹了。
HTML顯示結(jié)果
者：HelloGitHub-追夢(mèng)人物
在 Django博客教程（第二版）中，我們給博客內(nèi)容增加了 Markdown 的支持，博客詳情接口應(yīng)該返回解析后的 HTML 內(nèi)容。
來(lái)回顧一下 Post 模型的代碼，Markdown 解析后的 HTML 保存在這幾個(gè)屬性中：
rich_content 是 body Markdown 內(nèi)容解析后的 HTML 內(nèi)容，使用了 cached_property 裝飾器緩存解析后的結(jié)果，以降低多次訪問(wèn)的開(kāi)銷。body_html 屬性為解析后的正文內(nèi)容，toc 屬性是從正文標(biāo)題中提取的目錄。
toc 和 body_html 這兩個(gè)屬性的值是我們需要序列化并在接口中返回的，那么可否像之前那樣，直接在序列化器 PostRetrieveSerializer 的 Meta.fields 中添加這兩個(gè)屬性就行了呢？
答案是不能。之前說(shuō)過(guò)，模型字段不同類型的值都需要不同的序列化字段對(duì)其進(jìn)行序列化，我們之所以能直接在 Meta.fields 中指定需要序列化的字段而不需要額外的代碼是因?yàn)檫@些字段都是直接定義在 django 的模型中的。django-rest-framework 可以根據(jù)模型中的字段的定義自動(dòng)推斷該使用何種類型的序列化字段，但對(duì)于這里提到的 toc、body_html 屬性，django-rest-framework 就無(wú)法推斷其值的類型，也就無(wú)法自動(dòng)使用對(duì)應(yīng)的序列化字段對(duì)其進(jìn)行序列化了。不過(guò)解決方法很簡(jiǎn)單，既然 django-rest-framework 無(wú)法自動(dòng)推斷，那我們就人工指定該使用何種類型的序列化字段就行了。
這里需要序列化的字段值都是字符串，因此在序列化器中顯示地指定需要序列化的字段以及使用的系列化字段類型就可以了：
添加完成后，訪問(wèn)一篇文章的詳情接口，就可以看到被序列化并返回的文章目錄和正文 HTML 內(nèi)容了。
『講解開(kāi)源項(xiàng)目系列』——讓對(duì)開(kāi)源項(xiàng)目感興趣的人不再畏懼、讓開(kāi)源項(xiàng)目的發(fā)起者不再孤單。跟著我們的文章，你會(huì)發(fā)現(xiàn)編程的樂(lè)趣、使用和發(fā)現(xiàn)參與開(kāi)源項(xiàng)目如此簡(jiǎn)單。歡迎留言聯(lián)系我們、加入我們，讓更多人愛(ài)上開(kāi)源、貢獻(xiàn)開(kāi)源～
*請(qǐng)認(rèn)真填寫需求信息，我們會(huì)在24小時(shí)內(nèi)與您取得聯(lián)系。
