使用Swagger2Markup实现导出API文档

原文出处：使用Swagger2Markup实现导出API文档

一、通过Java代码来生成

第一步：编辑pom.xml增加需要使用的相关依赖和仓库

    io.github.swagger2markup
    swagger2markup
    1.3.3


    
        
            true
            always
        
        jcenter-releases
        jcenter
        http://jcenter.bintray.com
    

第二步：编写一个单元测试用例来生成执行生成文档的代码

/**
     * 生成AsciiDocs格式文档,并汇总成一个文件
     * @throws Exception
     */
    @Test
    public void generateAsciiDocsToFile() 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:8082/v2/api-docs"))
                .withConfig(config)
                .build()
                .toFile(Paths.get("./docs/asciidoc/generated/all"));
    }

以上代码内容很简单，大致说明几个关键内容：

• MarkupLanguage.ASCIIDOC：指定了要输出的最终格式。除了ASCIIDOC之外，还有MARKDOWN和CONFLUENCE_MARKUP
• from(new URL("http://localhost:8080/v2/api-docs")：指定了生成静态部署文档的源头配置，可以是这样的URL形式，也可以是符合Swagger规范的String类型或者从文件中读取的流。如果是对当前使用的Swagger项目，我们通过使用访问本地Swagger接口的方式，如果是从外部获取的Swagger文档配置文件，就可以通过字符串或读文件的方式
• toFolder(Paths.get("src/docs/asciidoc/generated")：指定最终生成文件的具体目录位置

输出到单个文件

如果不想分割结果文件，也可以通过替换toFolder(Paths.get("src/docs/asciidoc/generated")为toFile(Paths.get("src/docs/asciidoc/generated/all"))，将转换结果输出到一个单一的文件中，这样可以最终生成html的也是单一的。

 

二、通过Maven插件来生成

除了通过上面编写Java代码来生成的方式之外，swagger2markup还提供了对应的Maven插件来使用。对于上面的生成方式，完全可以通过在pom.xml中增加如下插件来完成静态内容的生成。

                org.asciidoctor
                asciidoctor-maven-plugin
                1.5.6
               
                    ./docs/asciidoc/generated
                    ./docs/asciidoc/html
                    true
                    book
                    html
                    coderay
                   
                       
                        left
                       
                        3
                       
                        true
                   
               
           

配置执行命令

通过上面的配置，执行该插件的asciidoctor:process-asciidoc命令之后，就能在docs/asciidoc/html目录下生成最终可用的静态部署HTML了。在完成生成之后，可以直接通过浏览器来看查看，你就能看到类似下图的静态部署结果：