通過swagger2markup+asciidoctorj生成html和pdf文檔並解決asciidoctorj生成的pdf文件中文顯示不全問題（maven方式及java代碼方式）

通過swagger2markup+asciidoctorj生成html和pdf文檔（maven方式及java代碼方式）

任務：通過同事的json文件生成相應的html和pdf文檔

前言

    開始時swagger2markup和asciidoctorj是什么都不知道，只能百度，看官方文檔（翻譯。。。），
遇到問題就一頭霧水，完全不知道哪里出了問題，要怎么決解，百度上資料（中文？）也是寥寥無幾，maven
也是沒有系統學習過，導致很多小問題到了自己這里變成了大麻煩。在經歷了一個星期的摸索，終於小有所成，
在此寫下自己嘔心瀝血的過程，以免日后自己忘了，也給其他同僚多一份可以參考的資料。

---

如果有寫的不好的地方，還望指出。

---

以下是我經歷一個星期的各種碰撞過程
- 使用maven插件方法生成html和pdf文件（json文件生成adoc文件，adoc文件再生成html和pdf文件）
- 使用java代碼方式生成adoc文件
- 使用java代碼方式調用cmd執行mvn test命令生成html和pdf文件
出現問題：生成的pdf中文顯示不全
解決：
- 使用asciidoctorj工具（單獨）在cmd里生成pdf文件
- 使用java代碼方式直接生成pdf文件（需adoc文件）

---

目錄

 

• 通過swagger2markupasciidoctorj生成html和pdf文檔maven方式及java代碼方式
  • 前言
  • 生成html和pdf文檔
    • 1使用maven插件方法生成html和pdf文件 json文件生成adoc文件 adoc文件再生成html和pdf文件
      • 可能出現的異常
      • 附圖
    • 2使用java代碼方式生成adoc文件
      • 附圖
    • 3使用代碼方式調用cmd執行mvn test命令生成html和pdf文件
      • 結構圖
      • 文件內容
  • 解決上面生成的pdf文件中文顯示不全問題
    • 1使用asciidoctorj工具單獨在cmd里生成pdf文件
    • 2使用java代碼方式直接生成pdf文件需adoc文件

 

生成html和pdf文檔

1、使用maven插件方法生成html和pdf文件 （json文件生成adoc文件， adoc文件再生成html和pdf文件）

參考文檔

• 導入eclipse后發現只有幾個可用
  
  
  • 可以看到pom.xml文件內有如下配置文件

<!-- 一些參數 --> <properties> <java.version>1.8</java.version> <swagger2markup.version>1.2.0</swagger2markup.version> <asciidoctor.input.directory>${project.basedir}/src/docs/asciidoc</asciidoctor.input.directory> <swagger.output.dir>${project.build.directory}/swagger</swagger.output.dir> <swagger.snippetOutput.dir>${project.build.directory}/asciidoc/snippets</swagger.snippetOutput.dir> <generated.asciidoc.directory>${project.build.directory}/asciidoc/generated</generated.asciidoc.directory> <asciidoctor.html.output.directory>${project.build.directory}/asciidoc/html</asciidoctor.html.output.directory> <asciidoctor.pdf.output.directory>${project.build.directory}/asciidoc/pdf</asciidoctor.pdf.output.directory> <swagger.input>${swagger.output.dir}/swagger.json</swagger.input> </properties> <!-- 首先是兩個遠程倉庫 --> <pluginRepositories> <pluginRepository> <id>jcenter-snapshots</id> <name>jcenter</name> <url>http://oss.jfrog.org/artifactory/oss-snapshot-local/</url> </pluginRepository> <pluginRepository> <id>jcenter-releases</id> <name>jcenter</name> <url>http://jcenter.bintray.com</url> <snapshots> <enabled>false</enabled> </snapshots> </pluginRepository> </pluginRepositories> <repositories> <repository> <id>jcentral</id> <name>bintray</name> <url>http://jcenter.bintray.com</url> <snapshots> <enabled>false</enabled> </snapshots> </repository> <repository> <id>jcenter-snapshots</id> <name>jcenter</name> <url>http://oss.jfrog.org/artifactory/oss-snapshot-local/</url> </repository> </repositories> <!-- 以下用於生成adoc文件的配置 --> <plugin> <groupId>io.github.swagger2markup</groupId> <artifactId>swagger2markup-maven-plugin</artifactId> <version>${swagger2markup.version}</version> <dependencies> <dependency> <groupId>io.github.swagger2markup</groupId> <artifactId>swagger2markup-import-files-ext</artifactId> <version>${swagger2markup.version}</version> </dependency> <dependency> <groupId>io.github.swagger2markup</groupId> <artifactId>swagger2markup-spring-restdocs-ext</artifactId> <version>${swagger2markup.version}</version> </dependency> </dependencies> <configuration> <swaggerInput>${swagger.input}</swaggerInput> <outputDir>${generated.asciidoc.directory}</outputDir> <config> <swagger2markup.markupLanguage>ASCIIDOC</swagger2markup.markupLanguage> <swagger2markup.pathsGroupedBy>TAGS</swagger2markup.pathsGroupedBy> <swagger2markup.extensions.dynamicOverview.contentPath>${project.basedir}/src/docs/asciidoc/extensions/overview</swagger2markup.extensions.dynamicOverview.contentPath> <swagger2markup.extensions.dynamicDefinitions.contentPath>${project.basedir}/src/docs/asciidoc/extensions/definitions</swagger2markup.extensions.dynamicDefinitions.contentPath> <swagger2markup.extensions.dynamicPaths.contentPath>${project.basedir}/src/docs/asciidoc/extensions/paths</swagger2markup.extensions.dynamicPaths.contentPath> <swagger2markup.extensions.dynamicSecurity.contentPath>${project.basedir}src/docs/asciidoc/extensions/security/</swagger2markup.extensions.dynamicSecurity.contentPath> <swagger2markup.extensions.springRestDocs.snippetBaseUri>${swagger.snippetOutput.dir}</swagger2markup.extensions.springRestDocs.snippetBaseUri> <swagger2markup.extensions.springRestDocs.defaultSnippets>true</swagger2markup.extensions.springRestDocs.defaultSnippets> </config> </configuration> <executions> <execution> <phase>test</phase> <goals> <goal>convertSwagger2markup</goal> </goals> </execution> </executions> </plugin> <!-- 以下配置用於生成html和pdf --> <plugin> <groupId>org.asciidoctor</groupId> <artifactId>asciidoctor-maven-plugin</artifactId> <version>1.5.3</version> <dependencies> <dependency> <groupId>org.asciidoctor</groupId> <artifactId>asciidoctorj-pdf</artifactId> <version>1.5.0-alpha.10.1</version> </dependency> <dependency> <groupId>org.jruby</groupId> <artifactId>jruby-complete</artifactId> <version>1.7.21</version> </dependency> </dependencies> <configuration> <sourceDirectory>${asciidoctor.input.directory}</sourceDirectory> <sourceDocumentName>index.adoc</sourceDocumentName> <attributes> <doctype>book</doctype> <toc>left</toc> <toclevels>3</toclevels> <numbered></numbered> <hardbreaks></hardbreaks> <sectlinks></sectlinks> <sectanchors></sectanchors> <generated>${generated.asciidoc.directory}</generated> </attributes> </configuration> <executions> <execution> <id>output-html</id> <phase>test</phase> <goals> <goal>process-asciidoc</goal> </goals> <configuration> <backend>html5</backend> <outputDirectory>${asciidoctor.html.output.directory}</outputDirectory> </configuration> </execution> <execution> <id>output-pdf</id> <phase>test</phase> <goals> <goal>process-asciidoc</goal> </goals> <configuration> <backend>pdf</backend> <outputDirectory>${asciidoctor.pdf.output.directory}</outputDirectory> </configuration> </execution> </executions> </plugin>

 

• 將以上配置放入pom.xml后替換你的json文件到
  ${project.build.directory}1/swagger/swagger.json
• 運行maven test后將在
  ${project.build.directory}/asciidoc/html
  和
  ${project.build.directory}/asciidoc/pdf
  目錄下分別生成html和pdf文件

可能出現的異常

1.[ERROR] Failed to execute goal io.github.swagger2markup:swagger2markup-maven-plugin:1.2.0:convertSwagger2markup (default) on project csdnTest: Execution default of goal io.github.swagger2markup:swagger2markup-maven-plugin:1.2.0:convertSwagger2markup failed: Unable to load the mojo 'convertSwagger2markup' in the plugin 'io.github.swagger2markup:swagger2markup-maven-plugin:1.2.0' due to an API incompatibility: org.codehaus.plexus.component.repository.exception.ComponentLookupException: io/github/swagger2markup/Swagger2MarkupMojo : Unsupported major.minor version 52.0 <!-- 請使用JDK 1.8版本 -->

附圖

1.新建一個maven項目

2.更改或添加至如下

pom.xml內容上面已經給出，你可能需要自己添加以下等配置

<build>
<plugins>
</plugins>
</build>

index.adoc文件內容為

include::{generated}/overview.adoc[] include::{generated}/paths.adoc[] include::{generated}/security.adoc[] include::{generated}/definitions.adoc[]

swagger.json文件替換成你的文件
可參考：http://petstore.swagger.io/v2/swagger.json

3.執行以下操作后等程序運行完再刷新一下就能看到生成的文檔了

2、使用java代碼方式生成adoc文件

使用代碼的方式相對較為靈活，下面上代碼

import io.github.swagger2markup.Swagger2MarkupConfig; import io.github.swagger2markup.Swagger2MarkupConverter; import io.github.swagger2markup.builder.Swagger2MarkupConfigBuilder; import java.net.URL; import java.nio.file.Path; import java.nio.file.Paths; import org.apache.commons.configuration2.Configuration; import org.apache.commons.configuration2.builder.fluent.Configurations; public class Swagger2Markup { //指定adoc文件生成路徑 public Path outputDirectory = Paths.get("target/asciidoc/generated"); //通過配置文件生成swagger2markup的參數 public Swagger2MarkupConfig config; public Swagger2Markup(String Json) throws Exception{ //讀取配置文件 Configuration configuration = new Configurations().properties("config.properties"); config = new Swagger2MarkupConfigBuilder(configuration).build(); if(Json.startsWith("http")){ //獲取遠程json數據 createAdocFile(new URL(Json)); }else{ //獲取本地json數據 createAdocFile(Paths.get(Json)); } } /** * 通過url生成adoc文件 */ public void createAdocFile(URL remoteSwaggerFile){ Swagger2MarkupConverter.from(remoteSwaggerFile) .withConfig(config) .build() .toFolder(outputDirectory); } /** * 通過json文件生成adoc文件 */ public void createAdocFile(Path localSwaggerFile){ Swagger2MarkupConverter.from(localSwaggerFile) .withConfig(config) .build() .toFolder(outputDirectory); } public static void main(String[] args) throws Exception{ //指定本地json文件路徑 new Swagger2Markup("target/swagger/swagger.json"); //指定遠程json文件路徑 // new Swagger2Markup("http://petstore.swagger.io/v2/swagger.json"); } } 

 

config.properties文件內容如下

swagger2markup.markupLanguage = ASCIIDOC swagger2markup.outputLanguage = EN

 

pom.xml文件內容：

<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd"> <modelVersion>4.0.0</modelVersion> <groupId>swaggerTest</groupId> <artifactId>swaggerTest</artifactId> <version>1.0</version> <repositories> <repository> <id>jcentral</id> <name>bintray</name> <url>http://jcenter.bintray.com</url> <snapshots> <enabled>false</enabled> </snapshots> </repository> <repository> <id>jcenter-snapshots</id> <name>jcenter</name> <url>http://oss.jfrog.org/artifactory/oss-snapshot-local/</url> </repository> </repositories> <dependencies> <dependency> <groupId>io.github.swagger2markup</groupId> <artifactId>swagger2markup</artifactId> <version>1.3.1</version> </dependency> </dependencies> </project> 

 

運行main方法后將會在target/asciidoc/generated/下生成4個adoc文件

附圖

3、使用代碼方式調用cmd執行mvn test命令生成html和pdf文件

在用代碼方式生成adoc文件之后就想着能不能再用代碼的方式省略掉手工步驟，結果苦尋無門，最后想出了最笨的方法算是實現了。。。

結構圖

文件內容

Swagger2Markup文件內容

package com.swaggerTest.base; import java.io.BufferedWriter; import java.io.File; import java.io.FileOutputStream; import java.io.IOException; import java.io.OutputStreamWriter; import java.nio.file.Paths; public class Swagger2Markup { public Swagger2Markup() throws Exception{ createHtmlFile(); } /** * 創建html和pdf文件 * @throws Exception */ public void createHtmlFile() throws Exception{ //獲取pom.xml的絕對路徑 String path = returnPath("pom.xml"); //生成bat文件的內容 StringBuilder batFileContent = new StringBuilder(path.substring(0, 2)).append("\r\n"); batFileContent.append("cd ").append(path.substring(0,path.length()-7)).append("\r\n"); batFileContent.append("mvn test"); //寫入到bat文件 writeInBatFile("src/cmd/bat.bat",batFileContent.toString().replace("/", "\\")); //生成vbs文件內容 StringBuilder vbsFileContent = new StringBuilder("Set ws = CreateObject(\"Wscript.Shell\")").append("\r\n"); vbsFileContent.append("ws.run \"cmd /c ").append(returnPath("src/cmd/bat.bat").replace("/", "\\")).append("\",vbhide"); //寫入vbs文件 writeInBatFile("src/cmd/vbs.vbs",vbsFileContent.toString()); //生成執行vbs文件命令(用vbs隱藏bat文件執行時的窗口) StringBuilder cmd = new StringBuilder("cmd /c CScript ").append(returnPath("src/cmd/vbs.vbs")); System.out.println(cmd.toString()); Process process = Runtime.getRuntime().exec(cmd.toString()); System.out.println(process.waitFor()); } /** * 生成文件 * @param content */ public void writeInBatFile(String fileName,String content){ File batFile = new File(returnPath(fileName)); //如果文件存在，則刪除 if(batFile != null && batFile.exists()){ batFile.delete(); } try { //創建gbk格式的文件（utf-8中文在cmd里亂碼） OutputStreamWriter out = new OutputStreamWriter(new FileOutputStream(batFile),"GBK"); BufferedWriter bw = new BufferedWriter(out); bw.write(content); bw.close(); out.close(); } catch (IOException e) { e.printStackTrace(); } } /** * 獲取指定文件路徑 * @param filePath * @return */ public String returnPath(String filePath){ return Paths.get(filePath).toAbsolutePath().toString(); } public static void main(String[] args) throws Exception{ new Swagger2Markup(); } } 

pom.xml文件內容

<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd"> <modelVersion>4.0.0</modelVersion> <groupId>swaggerTest</groupId> <artifactId>swaggerTest</artifactId> <version>1.0</version> <properties> <asciidoctor.input.directory>${project.basedir}/src/docs/asciidoc</asciidoctor.input.directory> <generated.asciidoc.directory>${project.build.directory}/asciidoc/generated</generated.asciidoc.directory> <asciidoctor.html.output.directory>${project.build.directory}/asciidoc/html</asciidoctor.html.output.directory> <asciidoctor.pdf.output.directory>${project.build.directory}/asciidoc/pdf</asciidoctor.pdf.output.directory> </properties> <repositories> <repository> <id>jcentral</id> <name>bintray</name> <url>http://jcenter.bintray.com</url> <snapshots> <enabled>false</enabled> </snapshots> </repository> <repository> <id>jcenter-snapshots</id> <name>jcenter</name> <url>http://oss.jfrog.org/artifactory/oss-snapshot-local/</url> </repository> </repositories> <build> <plugins> <plugin> <groupId>org.asciidoctor</groupId> <artifactId>asciidoctor-maven-plugin</artifactId> <version>1.5.3</version> <dependencies> <dependency> <groupId>org.asciidoctor</groupId> <artifactId>asciidoctorj-pdf</artifactId> <version>1.5.0-alpha.10.1</version> </dependency> <dependency> <groupId>org.jruby</groupId> <artifactId>jruby-complete</artifactId> <version>1.7.21</version> </dependency> </dependencies> <configuration> <sourceDirectory>${asciidoctor.input.directory}</sourceDirectory> <sourceDocumentName>index.adoc</sourceDocumentName> <attributes> <doctype>book</doctype> <toc>left</toc> <toclevels>3</toclevels> <numbered></numbered> <hardbreaks></hardbreaks> <sectlinks></sectlinks> <sectanchors></sectanchors> <generated>${generated.asciidoc.directory}</generated> </attributes> </configuration> <executions> <execution> <id>output-html</id> <phase>test</phase> <goals> <goal>process-asciidoc</goal> </goals> <configuration> <backend>html5</backend> <outputDirectory>${asciidoctor.html.output.directory}</outputDirectory> </configuration> </execution> <execution> <id>output-pdf</id> <phase>test</phase> <goals> <goal>process-asciidoc</goal> </goals> <configuration> <backend>pdf</backend> <outputDirectory>${asciidoctor.pdf.output.directory}</outputDirectory> </configuration> </execution> </executions> </plugin> </plugins> </build> </project> 

index.adoc文件內容不變

include::{generated}/overview.adoc[] include::{generated}/paths.adoc[] include::{generated}/security.adoc[] include::{generated}/definitions.adoc[]

asciidoc/generated/下的四個文件是上一節生成的。

運行main方法后刷新一下（生成pdf時間比較久）

解決上面生成的pdf文件中文顯示不全問題

1、使用asciidoctorj工具（單獨）在cmd里生成pdf文件

首先需要安裝一個 Chocolatey (不想安裝的可以跳過看下一個節點)
使用cmd.ext進行安裝，運行一下命令

@"%SystemRoot%\System32\WindowsPowerShell\v1.0\powershell.exe" -NoProfile -InputFormat None -ExecutionPolicy Bypass -Command "iex ((New-Object System.Net.WebClient).DownloadString('https://chocolatey.org/install.ps1'))" && SET "PATH=%PATH%;%ALLUSERSPROFILE%\chocolatey\bin"

安裝好后安裝asciidoctorj

C:\> choco install asciidoctorj C:\> where asciidoctorj C:\ProgramData\chocolatey\bin\asciidoctorj.exe 進入asciidoctorj目錄 C:\> asciidoctorj -b pdf index.adoc 生成pdf文件

 

如果全部安裝完成后可以參考https://github.com/asciidoctor/asciidoctor-pdf/blob/master/docs/theming-guide.adoc#custom-fonts

在C:\ProgramData\chocolatey\lib\asciidoctorj\tools\asciidoctorj-1.5.6\lib目錄下有一個asciidoctorj-pdf-1.5.0-alpha.16.jar文件

將gems\asciidoctor-pdf-1.5.0.alpha.16\data下的fonts文件夾和gems\asciidoctor-pdf-1.5.0.alpha.16\data\themes下的default-theme.yml文件復制到本地

替換fonts里的四個文件（正常字體，斜體，粗體，粗斜體）或者修改theme.yml（default-theme.yml）文件指向的字體

替換好后在cmd上運行命令 ：
asciidoctorj -a pdf-style=d:\pdfTest\theme.yml -a pdf-fontsdir=d:\pdfTest\fonts -b pdf d:\pdfTest\index.adoc
將會在當前目錄下生成pdf文件

2、使用java代碼方式直接生成pdf文件（需adoc文件）

在用cmd運行的時候出現錯誤，發現其調用的是class文件，然后想着手動去調用他的main方法。

pom.xml文件需要添加依賴

    <dependencies> <dependency> <groupId>org.asciidoctor</groupId> <artifactId>asciidoctorj-pdf</artifactId> <version>1.5.0-alpha.10.1</version> </dependency> </dependencies>

 

代碼部分，重點是最后一行就可以了

//樣式 String style = "pdf-style=d:\\pdfTest\\theme.yml"; //字體 String fontsdir = "pdf-fontsdir=d:\\pdfTest\\fonts"; //需要指定adoc文件位置 String adocPath = "d:\\pdfTest\\index.adoc"; org.asciidoctor.cli.AsciidoctorInvoker.main(new String[]{"-a",style,"-a",fontsdir,"-b","pdf",adocPath}); 

 

---

1. ${project.build.directory}是maven生成的文件的根目錄：target的絕對路徑 ↩