spring_swagger:static docs（离线文档）

背景

对于rest-ful API文档设计，一般都是springfox（底层是swagger）进行代码集成并且自动生成，文档分为在线和离线文档，在线文档一般是html的格式，并且能够进行mock，方便测试人员不用写test-case进行测试。

springfox reference 提示已经不支持离线文档的自动生成，推荐使用使用swagger2markup+assicdoctor.以下介绍怎样自动产生离线文档。

swagger2markup

用途：将springfox产生的api-docs api（包括API所有元信息），输出的json格式数据转变为assicdoc文件。
1.依赖包

        <dependency>
            <groupId>io.github.swagger2markupgroupId>
            <artifactId>swagger2markupartifactId>
            <version>${swagger2markup.version}version>
        dependency>

test 类

    String url="/v2/api-docs";
     try{
     MvcResult mvcResult = mvc.perform(MockMvcRequestBuilders.get(url)).andExpect(status().isOk()).andReturn();
     MockHttpServletResponse response = mvcResult.getResponse();
     String swaggerJson = response.getContentAsString();
     Path outputDirectory = Paths.get("");
      Swagger2MarkupConverter.from(swaggerJson)
        .build()
        .toFolder(outputDirectory);
      }catch(Exception e){
          log.error(e.getMessage());
      } 
}

2.使用插件，通过配置生产assicdoctor文件

        
        
            io.github.swagger2markup
            swagger2markup-maven-plugin
            ${swagger2markup.version}
            
                
                    io.github.swagger2markup
                    swagger2markup-import-files-ext
                    ${swagger2markup.version}
                
                
                    io.github.swagger2markup
                    swagger2markup-spring-restdocs-ext
                    ${swagger2markup.version}
                
            
            
                ${swagger.input}
                ${generated.asciidoc.directory}
                
                    ASCIIDOC
                    TAGS

                    ${project.basedir}/src/docs/asciidoc/extensions/overview
                    ${project.basedir}/src/docs/asciidoc/extensions/definitions
                    ${project.basedir}/src/docs/asciidoc/extensions/paths
                    ${project.basedir}src/docs/asciidoc/extensions/security/

                    ${swagger.snippetOutput.dir}
                    true
                
            
            
                
                    test
                    
                        convertSwagger2markup
                    
                
            
        

assicdoctor

用途：将assicdoc文件转化为html或者pdf文件。也是依赖包和插件模式（因为时间的原因，只实践了插件模式）

        
            org.asciidoctor
            asciidoctor-maven-plugin
            1.5.3
            
            
                
                    org.asciidoctor
                    asciidoctorj-pdf
                    1.5.0-alpha.10.1
                
                
                    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}
                    
                

                
                    output-pdf
                    test
                    
                        process-asciidoc
                    
                    
                        pdf
                        ${asciidoctor.pdf.output.directory}
                    
                

            
        

        
        
            org.apache.maven.plugins
            maven-jar-plugin
            2.4
            
                
                    
                        true
                        lib/
                        io.github.robwin.swagger2markup.petstore.Application
                    
                
            
        

        
        
            maven-dependency-plugin
            
                
                    package
                    
                        copy-dependencies
                    
                    
                        ${project.build.directory}/lib
                    
                
            
        

        
        
            maven-resources-plugin
            2.7
            
                
                    copy-resources
                    prepare-package
                    
                        copy-resources
                    
                    
                        ${project.build.outputDirectory}/static/docs
                        
                            
                                ${asciidoctor.html.output.directory}
                            
                            
                                ${asciidoctor.pdf.output.directory}
                            
                        
                    
                
            
        

参考

springfox reference
swagger2markup reference