SpringBoot2结合swagger2自动生成接口文档

背景

在 使用springboot 的大背景下，java 开发也相当顺当了，日常开发中，大都采用分层架构，后端研发要写很多文档，有时候会很麻烦。本文结合 swagger2 来自动生成文档。

技术

导入 swagger 依赖包：

        
            io.springfox
            springfox-swagger2
            2.9.2
            
                
                    guava
                    com.google.guava
                
            
        
        
            io.springfox
            springfox-swagger-ui
            2.9.2
        
        
            com.github.xiaoymin
            swagger-bootstrap-ui
            1.9.3
        
        
            io.springfox
            springfox-bean-validators
            2.9.2
            
                
                    guava
                    com.google.guava
                
            
        

通过 swagger2 的文件生成ASCIIDOC格式文件
导入依赖包：

            io.github.swagger2markup
            swagger2markup
            1.3.3
            
                
                    jackson-coreutils
                    com.github.fge
                
                
                    guava
                    com.google.guava
                
            
        

需要配置 plugin:

            
                io.github.swagger2markup
                swagger2markup-maven-plugin
                1.2.0
                
                    http://localhost:8080/v2/api-docs
                    ./docs/asciidoc/generated
                    
                        ASCIIDOC
                    
                
            
            
            
                org.asciidoctor
                asciidoctor-maven-plugin
                1.5.6
                
                    
                        org.asciidoctor
                        asciidoctorj-pdf
                        1.5.0-alpha.10.1
                    
                    
                        org.jruby
                        jruby-complete
                        1.7.21
                    
                
                
                    ./docs/asciidoc/generated
                    coderay
                    
                        book
                        left
                        3
                        
                        
                        
                        
                    
                

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

需要加一个swagger配置

import io.github.swagger2markup.GroupBy;
import io.github.swagger2markup.Language;
import io.github.swagger2markup.Swagger2MarkupConfig;
import io.github.swagger2markup.Swagger2MarkupConverter;
import io.github.swagger2markup.builder.Swagger2MarkupConfigBuilder;
import io.github.swagger2markup.markup.builder.MarkupLanguage;
import org.junit.Test;
import org.junit.runner.RunWith;
import org.springframework.boot.test.context.SpringBootTest;
import org.springframework.test.context.junit4.SpringJUnit4ClassRunner;

import java.net.URL;
import java.nio.file.Paths;

@RunWith(SpringJUnit4ClassRunner.class)
@SpringBootTest(
        classes = Application.class,
        webEnvironment = SpringBootTest.WebEnvironment.DEFINED_PORT)
public class SwaggerTest {

    @Test
    public void generateAsciiDocs() throws Exception {

        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("file:/Users/admin/Downloads/api-docs.json"))
                .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"));
                .toFile(Paths.get("./docs/confluence/generated/all"));
    }

    /**
     * 生成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"));
    }
}

生成的API 文档如：

image.png

image.png

image.png

总结

swagger2生成文档插件还是很方便的，可以通过定制接口结构、层级等，给生成接口文档带来了很大的方便。开发接口时，只要定义好入参、出参，文档就ok了。