一、引入依赖
1. 新版
<dependency>
<groupId>io.github.swagger2markup</groupId>
<artifactId>swagger2markup</artifactId>
<version>1.3.2</version>
</dependency>
2. 旧版
<dependency>
<groupId>io.github.robwin</groupId>
<artifactId>swagger2markup</artifactId>
<version>0.9.2</version>
</dependency>
二、读取swagger.json生成ASCIIDOC或者MARKDOWN
1. 新版
Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder()
.withPathsGroupedBy(GroupBy.TAGS)
.withMarkupLanguage(MarkupLanguage.ASCIIDOC)
.withOutputLanguage(Language.ZH)
.build()
try {
Swagger2MarkupConverter.from(new URL("http://192.168.1.9:8888/api/swagger.json"))
.withConfig(config)
.build()
.toFolder(Paths.get("src/docs"))
} catch (MalformedURLException e) {
e.printStackTrace()
}
2. 旧版
Swagger2MarkupConverter.from("json" + "/swagger.json")
.withPathsGroupedBy(GroupBy.TAGS)/
.withMarkupLanguage(MarkupLanguage.ASCIIDOC)
.build()
.intoFolder("doc")
三、利用maven插件asciidoctor-maven-plugin生成HTML5或PDF
<plugin>
<groupId>org.asciidoctor</groupId>
<artifactId>asciidoctor-maven-plugin</artifactId>
<version>1.5.6</version>
<configuration>
<sourceDirectory>${project.basedir}/src/docs</sourceDirectory>
<sourceDocumentName>index.adoc</sourceDocumentName>
<attributes>
<doctype>book</doctype>
<toc>left</toc>
<toclevels>3</toclevels>
<numbered></numbered>
<hardbreaks></hardbreaks>
<sectlinks></sectlinks>
<sectanchors></sectanchors>
<generated>${project.basedir}/src/docs</generated>
</attributes>
</configuration>
<executions>
<execution>
<id>output-html</id>
<phase>test</phase>
<goals>
<goal>process-asciidoc</goal>
</goals>
<configuration>
<backend>html5</backend>
<outputDirectory>${project.basedir}/src/docs2</outputDirectory>
</configuration>
</execution>
</executions>
</plugin>
四、执行命令mvn clean package
五、第三步亦可以用maven插件替代、第四步中亦可以用java代码替代生成
1. 如下是替代第三步做法
<plugin>
<groupId>com.github.kongchen</groupId>
<artifactId>swagger-maven-plugin</artifactId>
<version>3.1.1</version>
<configuration>
<apiSources>
<apiSource>
<springmvc>false</springmvc>
<locations>com.hiekn.demo.rest</locations>
<schemes>http,https</schemes>
<host>192.168.1.119:8080</host>
<basePath>/api</basePath>
<info>
<title>PlantRobot CMS API</title>
<version>v1</version>
<description>
</description>
<termsOfService>
http://blog.csdn.net/dh798417147
</termsOfService>
<contact>
<email>[email protected]</email>
<name>dinghao</name>
<url>http://blog.csdn.net/dh798417147</url>
</contact>
<license>
<url>http://www.apache.org/licenses/LICENSE-2.0.html</url>
<name>Apache 2.0</name>
</license>
</info>
<securityDefinitions>
</securityDefinitions>
<swaggerDirectory>${basedir}/json</swaggerDirectory>
</apiSource>
</apiSources>
</configuration>
<executions>
<execution>
<phase>compile</phase>
<goals>
<goal>generate</goal>
</goals>
</execution>
</executions>
<dependencies>
<dependency>
<groupId>io.swagger</groupId>
<artifactId>swagger-hibernate-validations</artifactId>
<version>1.5.6</version>
</dependency>
</dependencies>
</plugin>
2. 如下是替代第四步做法
<dependency>
<groupId>org.asciidoctor</groupId>
<artifactId>asciidoctorj</artifactId>
<version>1.5.6</version>
</dependency>
Asciidoctor asciidoctor = Asciidoctor.Factory.create()
Attributes attributes = new Attributes()
attributes.setCopyCss(true)
attributes.setLinkCss(false)
attributes.setSectNumLevels(3)
attributes.setAnchors(true)
attributes.setSectionNumbers(true)
attributes.setHardbreaks(true)
attributes.setTableOfContents(Placement.LEFT)
attributes.setAttribute("generated", "F:\\IDEAProject\\meta-boot\\src\\docs")
OptionsBuilder optionsBuilder = OptionsBuilder.options()
.backend("html5")
.docType("book")
.eruby("")
.inPlace(true)
.safe(SafeMode.UNSAFE)
.attributes(attributes)
String asciiInputFile = "src/docs/index.adoc"
asciidoctor.convertFile(
new File(asciiInputFile),
optionsBuilder.get())