使用swagger2markup导出swagger离线PDF/HTML文档

一、生成adoc文件

package com.bbd.onet.metadata.dao.impl;

import io.github.swagger2markup.GroupBy;
import io.github.swagger2markup.Language;
import io.github.swagger2markup.Swagger2MarkupConfig;
import io.github.swagger2markup.Swagger2MarkupConverter;
import io.github.swagger2markup.builder.Swagger2MarkupConfigBuilder;
import io.github.swagger2markup.markup.builder.MarkupLanguage;
import org.junit.Test;
import org.junit.runner.RunWith;
import org.springframework.test.context.junit4.SpringRunner;

import java.net.URL;
import java.nio.file.Paths;

/**
 * @Author Mr.Wang
 * @Date 2018/11/13 16:11
 */
@RunWith(SpringRunner.class)
public class exportConfig {
    @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:8765/v2/api-docs?group=api"))
                .withConfig(config)
                .build()
                .toFolder(Paths.get("src/docs/asciidoc/generated/all"));
    }
}

Maven 依赖：　

　　<dependency>
　　　　<groupId>io.github.swagger2markup</groupId>
　　　　<artifactId>swagger2markup</artifactId>
　　　　<version>1.3.1</version>
　　</dependency>

生成文件以下图：

 

二、将adoc文件转换成html/pdf 文件

<build>
    <plugins>
        <plugin>
            <groupId>io.github.swagger2markup</groupId>
            <artifactId>swagger2markup-maven-plugin</artifactId>
            <version>1.2.0</version>
            <configuration>
                <!--此处端口必定要是当前项目启动所用的端口-->
                <swaggerInput>http://localhost:8765/v2/api-docs?group=api</swaggerInput>
                <outputDir>src/docs/asciidoc/generated/all</outputDir>
                <config>
                    <!-- 除了ASCIIDOC以外，还有MARKDOWN和CONFLUENCE_MARKUP可选 -->
                    <swagger2markup.markupLanguage>ASCIIDOC</swagger2markup.markupLanguage>
                </config>
            </configuration>
        </plugin>

        <plugin>
            <groupId>org.asciidoctor</groupId>
            <artifactId>asciidoctor-maven-plugin</artifactId>
            <version>1.5.3</version>
            <!-- Include Asciidoctor PDF for pdf generation -->
            <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>
            <!-- Configure generic document generation settings -->
            <configuration>
                <sourceDirectory>src/docs/asciidoc/generated/all</sourceDirectory>
                <sourceHighlighter>coderay</sourceHighlighter>
                <attributes>
                    <toc>left</toc>
                </attributes>
            </configuration>
            <!-- Since each execution can only handle one backend, run
                 separate executions for each desired output type -->
            <executions>
                <execution>
                    <id>output-html</id>
                    <phase>generate-resources</phase>
                    <goals>
                        <goal>process-asciidoc</goal>
                    </goals>
                    <configuration>
                        <backend>html5</backend>
                        <outputDirectory>src/docs/asciidoc/html</outputDirectory>
                    </configuration>
                </execution>

                <execution>
                    <id>output-pdf</id>
                    <phase>generate-resources</phase>
                    <goals>
                        <goal>process-asciidoc</goal>
                    </goals>
                    <configuration>
                        <backend>pdf</backend>
                        <outputDirectory>src/docs/asciidoc/pdf</outputDirectory>
                    </configuration>
                </execution>

            </executions>
        </plugin>
    </plugins>
</build>

依次执行mvn指令：mvn asciidoctor:process-asciidoc  和 mvn generate-resources

生成文件如图：

 

 

注意：在生成adoc文件时，要启动项目。项目中要配置swagger。