Swagger生成离线文档解析

Swagger框架生成离线文档分为三步：

1.使用Swagger生成Api界面，即http://localhost:8080/swagger-ui.html

2.使用springfox-staticdocs包里面给的静态文档模板生成策略生成静态文档。

3.使用Maven打包生成的静态文档模板。

生成Api界面请参照之前的博客，此处只介绍生成静态文档模板以及maven打包的方法。

Maven信息，

<?xml version="1.0" encoding="UTF-8"?>
<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>com.beauxie</groupId>
    <artifactId>swagger.export</artifactId>
    <version>0.0.1-SNAPSHOT</version>
    <packaging>jar</packaging>


    <properties>
        <snippetsDirectory>${project.build.directory}/generated-snippets</snippetsDirectory>

        <asciidoctor.input.directory>${project.basedir}/docs/asciidoc</asciidoctor.input.directory>
        <generated.asciidoc.directory>${project.build.directory}/asciidoc</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>

    <dependencies>

        <!--springfox-staticdocs 生成静态文档-->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-staticdocs</artifactId>
            <version>2.6.1</version>
        </dependency>
        <dependency>
            <groupId>junit</groupId>
            <artifactId>junit</artifactId>
            <version>4.11</version>
            <scope>test</scope>
        </dependency>
    </dependencies>

    <build>
        <plugins>
            <!--Maven通过Maven Surefire Plugin插件执行单元测试-->
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-surefire-plugin</artifactId>
                <configuration>
                    <testFailureIgnore>true</testFailureIgnore>
                </configuration>
            </plugin>
            <!-- Run the generated asciidoc through Asciidoctor to generate
                 other documentation types, such as PDFs or HTML5 -->
            <!--通过Asciidoctor使得asciidoc生成其他的文档格式，例如：PDF 或者HTML5-->
            <plugin>
                <groupId>org.asciidoctor</groupId>
                <artifactId>asciidoctor-maven-plugin</artifactId>
                <version>1.5.3</version>
                <!-- Include Asciidoctor PDF for pdf generation -->
                <!--生成PDF-->
                <dependencies>
                    <dependency>
                        <groupId>org.asciidoctor</groupId>
                        <artifactId>asciidoctorj-pdf</artifactId>
                        <version>1.5.0-alpha.14</version>
                    </dependency>

                    <!-- Comment this section to use the default jruby artifact provided by the plugin -->
                    <dependency>
                        <groupId>org.jruby</groupId>
                        <artifactId>jruby-complete</artifactId>
                        <version>1.7.21</version>
                    </dependency>
                </dependencies>

                <!-- Configure generic document generation settings -->
                <!--文档生成配置-->
                <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>
                <!-- Since each execution can only handle one backend, run
                   separate executions for each desired output type -->
                <!--因为每次执行只能处理一个后端，所以对于每个想要的输出类型，都是独立分开执行-->
                <executions>
                    <!--html5-->
                    <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>
                    <!--pdf 目前pdf生产会有问题，可采取html用Word文档打开再另存为的形式-->
             <!--       <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>

之后建立Test类用于生成静态文档模板，SwaggerExportTest类，

package com.beauxie.swagger.export;

import com.beauxie.swagger.export.utils.StreamTool;
import io.github.robwin.markup.builder.MarkupLanguage;
import io.github.robwin.swagger2markup.GroupBy;
import io.github.robwin.swagger2markup.Swagger2MarkupConverter;
import io.swagger.io.HttpClient;
import org.junit.Test;

import java.io.InputStream;

import static com.beauxie.swagger.export.constants.Constant.*;

/**
 * 将swagger-api文档导出成html
 *
 * @author Beauxie
 * @date Created on 2018/04/06
 */
public class SwaggerExportTest {
    /**
     * 服务器地址
     */
    private static String SERVICE_URL = "http://127.0.0.1:8080";

    static {
        StreamTool.checkFile(OUTPUT_DIR);
    }


    @Test
    public void test() throws Exception {
        outputJson();
        // 这个outputDir必须和插件里面<generated></generated>标签配置一致
        Swagger2MarkupConverter.from(FILE_PATH)
                .withPathsGroupedBy(GroupBy.TAGS)// 按tag排序
                .withMarkupLanguage(MarkupLanguage.ASCIIDOC)// 格式
                .withExamples(SNIPPET_DIR)
                .build()
                .intoFolder(OUTPUT_DIR);// 输出

    }

    public void outputJson() throws Exception {
        String url = SERVICE_URL + URI;
        HttpClient httpClient = new HttpClient(url);
        System.out.println("开始请求:" + url);
        InputStream ipputStream = httpClient.execute();
        byte[] data = StreamTool.read(ipputStream);
        System.out.println("请求结果:" + new String(data, "UTF-8"));
        StreamTool.saveDataToFile(data, FILE_PATH);
        System.out.println("请求结果已成功保存到本地:" + FILE_PATH);

    }

}

Constant静态参数配置，用于为Test提供静态配置。

package com.beauxie.swagger.export.constants;

/**
 * @author Beauxie
 * @date Created on 2018/04/06
 */
public class Constant {
    public static final String SNIPPET_DIR = "target/generated-snippets";
    public static final String OUTPUT_DIR = "target/asciidoc";
    public static final String URI = "/v2/api-docs";
    public static final String FILE_NAME = "swagger.json";
    public static final String FILE_PATH = OUTPUT_DIR + "/" + FILE_NAME;
}

StreamTool文件输出流，配置

package com.beauxie.swagger.export.utils;

import java.io.*;

/**
 * @author Beauxie
 * @date Created on 2018/04/06
 */
public class StreamTool {
    public static byte[] read(InputStream inStream) throws Exception {
        ByteArrayOutputStream outputStream = new ByteArrayOutputStream();
        byte[] buffer = new byte[1024];
        int len = 0;
        while ((len = inStream.read(buffer)) != -1) {
            outputStream.write(buffer, 0, len);
        }
        inStream.close();
        return outputStream.toByteArray();
    }

    /**
     * @param data     ：数据
     * @param filePath ：要保存的文件路径，包含文件名及其后缀
     * @author xiepuyao
     */
    public static void saveDataToFile(byte[] data, String filePath) throws IOException {

        OutputStream os = null;
        os = new FileOutputStream(new File(filePath));
        os.write(data, 0, data.length);
        os.flush();// 刷新缓冲区中的内容
        os.close();// 关闭输出流
    }

    public static  void checkFile(String filePath) {
        File file = new File(filePath);
        if (!file.exists()) {
            file.mkdirs();
            System.out.println("已创建目录:" + filePath);
        }
    }
}

之后运行test，得到四个模板文档，

进入项目路径执行mvn test生成Html文档，

文档生成情况如下