使用Swagger2Markup归档swagger生成的API文档

说明

项目中使用Swagger之后，我们能够很轻松的管理API文档，并非常简单的模拟接口调用，但是构建的文档必须通过在项目中整合 swagger-ui、或使用单独部署的 swagger-ui和 /v2/api-docs返回的配置信息才能展现出您所构建的API文档。本文将在使用Swagger的基础上，再介绍一种生成静态API文档的方法，以便于构建更轻量部署和使用的API文档。

Swagger2Markup简介

Swagger2Markup是Github上的一个开源项目。该项目主要用来将Swagger自动生成的文档转换成几种流行的格式以便于静态部署和使用，比如：AsciiDoc、Markdown、Confluence。

项目主页：https://github.com/Swagger2Markup/swagger2markup

如何使用

在使用Swagger2Markup之前，我们先需要准备一个使用了Swagger的Web项目，可以是直接使用Swagger2的项目

1. 引入依赖

   
       io.github.swagger2markup
       swagger2markup
       1.3.1
   
   
   
       
           
               true
               always
           
           jcenter-releases
           jcenter
           http://jcenter.bintray.com
       
   
   

2. 编写一个单元测试用例来生成执行生成文档的代码

    @RunWith(SpringRunner.class)
    @SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.DEFINED_PORT)
    public class SwaggerDemoApplicationTests {
    
        /**
         * 生成AsciiDocs格式文档
         * @throws Exception
         */
        @Test
        public void generateAsciiDocs() 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:8080/v2/api-docs"))
                    .withConfig(config)
                    .build()
                    .toFolder(Paths.get("./docs/asciidoc/generated"));
        }
    
        /**
         * 生成Markdown格式文档
         * @throws Exception
         */
        @Test
        public void generateMarkdownDocs() throws Exception {
            //  输出Markdown格式
            Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder()
                    .withMarkupLanguage(MarkupLanguage.MARKDOWN)
                    .withOutputLanguage(Language.ZH)
                    .withPathsGroupedBy(GroupBy.TAGS)
                    .withGeneratedExamples()
                    .withoutInlineSchema()
                    .build();
    
            Swagger2MarkupConverter.from(new URL("http://localhost:8080/v2/api-docs"))
                    .withConfig(config)
                    .build()
                    .toFolder(Paths.get("./docs/markdown/generated"));
        }
    
    
        /**
         * 生成Confluence格式文档
         * @throws Exception
         */
        @Test
        public void generateConfluenceDocs() throws Exception {
            //  输出Confluence使用的格式
            Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder()
                    .withMarkupLanguage(MarkupLanguage.CONFLUENCE_MARKUP)
                    .withOutputLanguage(Language.ZH)
                    .withPathsGroupedBy(GroupBy.TAGS)
                    .withGeneratedExamples()
                    .withoutInlineSchema()
                    .build();
    
            Swagger2MarkupConverter.from(new URL("http://localhost:8080/v2/api-docs"))
                    .withConfig(config)
                    .build()
                    .toFolder(Paths.get("./docs/confluence/generated"));
        }
    
        /**
         * 生成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:8080/v2/api-docs"))
                    .withConfig(config)
                    .build()
                    .toFile(Paths.get("./docs/asciidoc/generated/all"));
        }
    
        /**
         * 生成Markdown格式文档,并汇总成一个文件
         * @throws Exception
         */
        @Test
        public void generateMarkdownDocsToFile() throws Exception {
            //  输出Markdown到单文件
            Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder()
                    .withMarkupLanguage(MarkupLanguage.MARKDOWN)
                    .withOutputLanguage(Language.ZH)
                    .withPathsGroupedBy(GroupBy.TAGS)
                    .withGeneratedExamples()
                    .withoutInlineSchema()
                    .build();
    
            Swagger2MarkupConverter.from(new URL("http://localhost:8080/v2/api-docs"))
                    .withConfig(config)
                    .build()
                    .toFile(Paths.get("./docs/markdown/generated/all"));
    }
   

3. 使用maven插件生成HTML文档

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

效果

image

image

实际项目应用后效果

• [实际项目应用后效果](http://cdn-blog.jetbrains.org.cn/doc/all.html）

代码

https://github.com/changdaye/swagger-demo

鸣谢

文章出处 ： http://blog.didispace.com/swagger2markup-asciidoc/

image