springboot整合swagger、swaggerMarkup、knife4J

前言

随着前后端分离日益盛行，后端的工作减轻了不少，开发 -> 单元测试 -> 提供接口，一般地，我们会整合swagger等可视化接口工具，接口开发完成后将swagger链接交给前端即可。当然也可以通过swaggerMarkup生成离线接口文档，也可以整合功能更加完善、样式更加精美的knife4J

swagger

依赖导入

		
        
            io.springfox
            springfox-swagger2
            ${swagger2.veresion}
        
        
            io.springfox
            springfox-swagger-ui
            ${swagger2.veresion}
        

相关注解

• @Api(tags = "activemq整合")
  用在controller上，定义一类接口描述
• @ApiOperation(value = "queue消息发送")
  用在方法上，定义每个接口描述
• @ApiImplicitParams和@ApiImplicitParam
  搭配使用，定义接口参数，示例如下

	@ApiImplicitParams({
            @ApiImplicitParam(name = "message", value = "消息", required = true)
    })

整合结果

SwaggerMarkUp

相关依赖

		
        
            io.github.swagger2markup
            swagger2markup
            1.3.1
        

插件整合

	
        
            
                org.asciidoctor
                asciidoctor-maven-plugin
                1.5.3
                
                
                    
                        org.asciidoctor
                        asciidoctorj-pdf
                        1.5.0-alpha.10.1
                    
                    
                        org.jruby
                        jruby-complete
                        1.7.24
                    
                
                
                
                    docs/asciidoc/generated
                    coderay
                    
                        left
                    
                
                
                
                    
                        output-html
                        generate-resources
                        
                            process-asciidoc
                        
                        
                            html5
                            docs/asciidoc/html
                        
                    
                    
                        output-pdf
                        generate-resources
                        
                            process-asciidoc
                        
                        
                            pdf
                            docs/asciidoc/pdf
                        
                    
                
            
        
    

上述插件包括了生成html，pdf文档的功能

创建对应文件夹

在项目下建立docs文件夹，以生成静态文档

编写如下单元测试类

/**
 * swagger markup test
 * @author dzcr
 */
@RunWith(SpringRunner.class)
@SpringBootTest(classes = ActiveMQApplication.class)
public class SwaggerTo {
    private String url = "http://localhost:10500/v2/api-docs";

    @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(url))
                .withConfig(config)
                .build()
                .toFolder(Paths.get("./docs/asciidoc/generated"));
    }

    @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(url))
                .withConfig(config)
                .build()
                .toFolder(Paths.get("./docs/markdown/generated"));
    }

    @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(url))
                .withConfig(config)
                .build()
                .toFile(Paths.get("./docs/asciidoc/generated/all"));
    }
 
    @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(url))
                .withConfig(config)
                .build()
                .toFile(Paths.get("./docs/markdown/generated/all"));
    }
}

注意地址改成实际地址

运行单元测试

如果运行报错无法找到BeanInterceptor类，升级common-beansutils.jar至1.9.2版本即可
生成文档如图

生成html、pdf文档

mvn install即可

静态文档效果图

knife4J

依赖导入

		
        
            com.github.xiaoymin
            knife4j-spring-boot-starter
            1.9.6
        

注解添加

在swagger配置类上添加@EnableSwaggerBootstrapUi注解即可

访问

http://ip:port/doc.html

功能强大（接口排序、参数缓存等等）
样式精美

资料

源码地址

https://github.com/dangzhicairang/my-cloud.git

配置中心地址

https://github.com/dangzhicairang/my-config.git