将swagger2接口 导出成文档 文档类型可以为html pdf

今天正好需要整理接口文档，所以就想偷个懒看看能否通过swagger来导出，网上查看了一些前辈们的资料发现还是蛮方便的，这里也留个足迹方便记忆。 首选说使用swagger2markup 导出adoc文档，我们需要依赖引入，这中间可能也会涉及到一些jar包冲突的问题，网上都能搜到可以自行解决（建议google搜）。

这里主要看 springfox-swagger2 依赖里的 swagger-models swagger-core的版本，我这里将是1.5.9 我讲版本换成了1.5.16

   
       io.swagger
       swagger-models
       1.5.16
   
   
       io.swagger
       swagger-core
       1.5.16
   

解决完冲突，继续往下

    
        io.github.swagger2markup
        swagger2markup
        1.3.1
    

然后写测试类

    @Test
    public void generateAsciiDocs() throws Exception {
        //    输出Ascii格式
        Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder()
                .withMarkupLanguage(MarkupLanguage.ASCIIDOC)
                .withOutputLanguage(Language.ZH)
                .withPathsGroupedBy(GroupBy.TAGS)
                .withGeneratedExamples()
                .withoutInlineSchema()
                .build();

        URL url = new URL("http://ip:端口/项目名/v2/api-docs");
        Swagger2MarkupConverter.from(url)
                .withConfig(config)
                .build()
                .toFolder(Paths.get("D:\\"));
    }

运行测试类后我们可以得到4个.adoc的文件。MarkupLanguage 可以用来设置生成的文档格式

然后再说生成html和pdf文档，需要添加的是生成ASCIIDOC所需要maven插件

    
    
        io.github.swagger2markup
        swagger2markup-maven-plugin
        1.2.0
        
            http://ip:当前项目端口/v2/api-docs
            src/docs/asciidoc/generated
            
                
                ASCIIDOC
            
        
    

输出PDF和HTML的maven插件

    
        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
            
        

        
            src/docs/asciidoc/generated
            coderay
            
                left
            
        

        
            
                output-html
                generate-resources
                
                    process-asciidoc
                
                
                    html5
                    src/docs/asciidoc/html
                
            

            
                output-pdf
                generate-resources
                
                    process-asciidoc
                
                
                    pdf
                    src/docs/asciidoc/pdf
                
            
        
    

配置好后首先需要运行asciidoctor-maven-plugin插件的命令去生成adoc文件,再运行generate-resources命令输出静态文档，因为该插件是根据adoc文件生成的PDF和HTML，所以顺序不能错，最后输出的PDF文件会在src/docs/asciidoc/pdf目录下面。

//生成adoc文件 mvn asciidoctor:process-asciidoc //生成pdf和html mvn generate-resources 这里要顺序执行，我在执行这第一个命令的时候发现了一个问题 控制台报 “io/console not supported; tty will not be manipulated”，网上搜了一下没找到解决的办法，可能我搜的不够仔细，要是有朋友知道 什么原因可以告知一下，反正第一个命令是为了生存.adoc的文件，所以我用第一步测试类生成了，然后执行命令2 ，顺利生成了html和pdf。

springcloud的一些基础框架搭建https://github.com/foryq。