Swagger生成离线文档解析

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

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

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

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

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

Maven信息，

    4.0.0

    com.beauxie
    swagger.export
    0.0.1-SNAPSHOT
    jar


    
        ${project.build.directory}/generated-snippets

        ${project.basedir}/docs/asciidoc
        ${project.build.directory}/asciidoc
        ${project.build.directory}/asciidoc/html
        ${project.build.directory}/asciidoc/pdf
    

    

        
        
            io.springfox
            springfox-staticdocs
            2.6.1
        
        
            junit
            junit
            4.11
            test
        
    

    
        
            
            
                org.apache.maven.plugins
                maven-surefire-plugin
                
                    true
                
            
            
            
            
                org.asciidoctor
                asciidoctor-maven-plugin
                1.5.3
                
                
                
                    
                        org.asciidoctor
                        asciidoctorj-pdf
                        1.5.0-alpha.14
                    

                    
                    
                        org.jruby
                        jruby-complete
                        1.7.21
                    
                

                
                
                
                    ${asciidoctor.input.directory}
                    index.adoc
                    
                        book
                        left
                        3
                        
                        
                        
                        
                        ${generated.asciidoc.directory}
                    
                
                
                
                
                    
                    
                        output-html
                        test
                        
                            process-asciidoc
                        
                        
                            html5
                            ${asciidoctor.html.output.directory}
                        
                    
                    
             
                
            
        
    

之后建立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必须和插件里面标签配置一致
        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文档，

文档生成情况如下