通过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文件
- 结构图
- 文件内容
- 1使用maven插件方法生成html和pdf文件 json文件生成adoc文件 adoc文件再生成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.8java.version>
<swagger2markup.version>1.2.0swagger2markup.version>
<asciidoctor.input.directory>${project.basedir}/src/docs/asciidocasciidoctor.input.directory>
<swagger.output.dir>${project.build.directory}/swaggerswagger.output.dir>
<swagger.snippetOutput.dir>${project.build.directory}/asciidoc/snippetsswagger.snippetOutput.dir>
<generated.asciidoc.directory>${project.build.directory}/asciidoc/generatedgenerated.asciidoc.directory>
<asciidoctor.html.output.directory>${project.build.directory}/asciidoc/htmlasciidoctor.html.output.directory>
<asciidoctor.pdf.output.directory>${project.build.directory}/asciidoc/pdfasciidoctor.pdf.output.directory>
<swagger.input>${swagger.output.dir}/swagger.jsonswagger.input>
properties>
<pluginRepositories>
<pluginRepository>
<id>jcenter-snapshotsid>
<name>jcentername>
<url>http://oss.jfrog.org/artifactory/oss-snapshot-local/url>
pluginRepository>
<pluginRepository>
<id>jcenter-releasesid>
<name>jcentername>
<url>http://jcenter.bintray.comurl>
<snapshots>
<enabled>falseenabled>
snapshots>
pluginRepository>
pluginRepositories>
<repositories>
<repository>
<id>jcentralid>
<name>bintrayname>
<url>http://jcenter.bintray.comurl>
<snapshots>
<enabled>falseenabled>
snapshots>
repository>
<repository>
<id>jcenter-snapshotsid>
<name>jcentername>
<url>http://oss.jfrog.org/artifactory/oss-snapshot-local/url>
repository>
repositories>
<plugin>
<groupId>io.github.swagger2markupgroupId>
<artifactId>swagger2markup-maven-pluginartifactId>
<version>${swagger2markup.version}version>
<dependencies>
<dependency>
<groupId>io.github.swagger2markupgroupId>
<artifactId>swagger2markup-import-files-extartifactId>
<version>${swagger2markup.version}version>
dependency>
<dependency>
<groupId>io.github.swagger2markupgroupId>
<artifactId>swagger2markup-spring-restdocs-extartifactId>
<version>${swagger2markup.version}version>
dependency>
dependencies>
<configuration>
<swaggerInput>${swagger.input}swaggerInput>
<outputDir>${generated.asciidoc.directory}outputDir>
<config>
<swagger2markup.markupLanguage>ASCIIDOCswagger2markup.markupLanguage>
<swagger2markup.pathsGroupedBy>TAGSswagger2markup.pathsGroupedBy>
<swagger2markup.extensions.dynamicOverview.contentPath>${project.basedir}/src/docs/asciidoc/extensions/overviewswagger2markup.extensions.dynamicOverview.contentPath>
<swagger2markup.extensions.dynamicDefinitions.contentPath>${project.basedir}/src/docs/asciidoc/extensions/definitionsswagger2markup.extensions.dynamicDefinitions.contentPath>
<swagger2markup.extensions.dynamicPaths.contentPath>${project.basedir}/src/docs/asciidoc/extensions/pathsswagger2markup.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>trueswagger2markup.extensions.springRestDocs.defaultSnippets>
config>
configuration>
<executions>
<execution>
<phase>testphase>
<goals>
<goal>convertSwagger2markupgoal>
goals>
execution>
executions>
plugin>
<plugin>
<groupId>org.asciidoctorgroupId>
<artifactId>asciidoctor-maven-pluginartifactId>
<version>1.5.3version>
<dependencies>
<dependency>
<groupId>org.asciidoctorgroupId>
<artifactId>asciidoctorj-pdfartifactId>
<version>1.5.0-alpha.10.1version>
dependency>
<dependency>
<groupId>org.jrubygroupId>
<artifactId>jruby-completeartifactId>
<version>1.7.21version>
dependency>
dependencies>
<configuration>
<sourceDirectory>${asciidoctor.input.directory}sourceDirectory>
<sourceDocumentName>index.adocsourceDocumentName>
<attributes>
<doctype>bookdoctype>
<toc>lefttoc>
<toclevels>3toclevels>
<numbered>numbered>
<hardbreaks>hardbreaks>
<sectlinks>sectlinks>
<sectanchors>sectanchors>
<generated>${generated.asciidoc.directory}generated>
attributes>
configuration>
<executions>
<execution>
<id>output-htmlid>
<phase>testphase>
<goals>
<goal>process-asciidocgoal>
goals>
<configuration>
<backend>html5backend>
<outputDirectory>${asciidoctor.html.output.directory}outputDirectory>
configuration>
execution>
<execution>
<id>output-pdfid>
<phase>testphase>
<goals>
<goal>process-asciidocgoal>
goals>
<configuration>
<backend>pdfbackend>
<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内容上面已经给出，你可能需要自己添加以下等配置
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 = ENpom.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.0modelVersion>
<groupId>swaggerTestgroupId>
<artifactId>swaggerTestartifactId>
<version>1.0version>
<repositories>
<repository>
<id>jcentralid>
<name>bintrayname>
<url>http://jcenter.bintray.comurl>
<snapshots>
<enabled>falseenabled>
snapshots>
repository>
<repository>
<id>jcenter-snapshotsid>
<name>jcentername>
<url>http://oss.jfrog.org/artifactory/oss-snapshot-local/url>
repository>
repositories>
<dependencies>
<dependency>
<groupId>io.github.swagger2markupgroupId>
<artifactId>swagger2markupartifactId>
<version>1.3.1version>
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.0modelVersion>
<groupId>swaggerTestgroupId>
<artifactId>swaggerTestartifactId>
<version>1.0version>
<properties>
<asciidoctor.input.directory>${project.basedir}/src/docs/asciidocasciidoctor.input.directory>
<generated.asciidoc.directory>${project.build.directory}/asciidoc/generatedgenerated.asciidoc.directory>
<asciidoctor.html.output.directory>${project.build.directory}/asciidoc/htmlasciidoctor.html.output.directory>
<asciidoctor.pdf.output.directory>${project.build.directory}/asciidoc/pdfasciidoctor.pdf.output.directory>
properties>
<repositories>
<repository>
<id>jcentralid>
<name>bintrayname>
<url>http://jcenter.bintray.comurl>
<snapshots>
<enabled>falseenabled>
snapshots>
repository>
<repository>
<id>jcenter-snapshotsid>
<name>jcentername>
<url>http://oss.jfrog.org/artifactory/oss-snapshot-local/url>
repository>
repositories>
<build>
<plugins>
<plugin>
<groupId>org.asciidoctorgroupId>
<artifactId>asciidoctor-maven-pluginartifactId>
<version>1.5.3version>
<dependencies>
<dependency>
<groupId>org.asciidoctorgroupId>
<artifactId>asciidoctorj-pdfartifactId>
<version>1.5.0-alpha.10.1version>
dependency>
<dependency>
<groupId>org.jrubygroupId>
<artifactId>jruby-completeartifactId>
<version>1.7.21version>
dependency>
dependencies>
<configuration>
<sourceDirectory>${asciidoctor.input.directory}sourceDirectory>
<sourceDocumentName>index.adocsourceDocumentName>
<attributes>
<doctype>bookdoctype>
<toc>lefttoc>
<toclevels>3toclevels>
<numbered>numbered>
<hardbreaks>hardbreaks>
<sectlinks>sectlinks>
<sectanchors>sectanchors>
<generated>${generated.asciidoc.directory}generated>
attributes>
configuration>
<executions>
<execution>
<id>output-htmlid>
<phase>testphase>
<goals>
<goal>process-asciidocgoal>
goals>
<configuration>
<backend>html5backend>
<outputDirectory>${asciidoctor.html.output.directory}outputDirectory>
configuration>
execution>
<execution>
<id>output-pdfid>
<phase>testphase>
<goals>
<goal>process-asciidocgoal>
goals>
<configuration>
<backend>pdfbackend>
<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.asciidoctorgroupId>
<artifactId>asciidoctorj-pdfartifactId>
<version>1.5.0-alpha.10.1version>
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});
- ${project.build.directory}是maven生成的文件的根目录：target的绝对路径 ↩