JavaWeb日记——当springmvc遇上swagger2

大家都知道springmvc是JaveWeb里最流行的mvc框架，swagger也是最流行的文档生成工具，两个最流行的结合起来也只需要仅仅几分钟而已

目录结构

目录结构

POM

    4.0.0
    com.jk
    swagger2-springmvc-example
    war
    1.0
    SpringMVC Swagger Webapp
    http://maven.apache.org

    
        2.3.0
        4.2.4.RELEASE
        3.1.0
    

    
        
            javax.servlet
            jstl
            1.2
        
        
        
            com.fasterxml.jackson.core
            jackson-databind
            2.6.4
        
        
            org.codehaus.jackson
            jackson-mapper-asl
            1.9.13
        
        
        
            org.springframework
            spring-webmvc
            ${spring-version}
        
        
            org.springframework
            spring-context-support
            ${spring-version}
        
        
        
            io.springfox
            springfox-swagger2
            ${springfox-version}
        
        
            javax.servlet
            javax.servlet-api
            ${servlet-api-version}
            provided
        
    

web.xml

    Spring Web MVC Application

    
    
        mvc-dispatcher
        org.springframework.web.servlet.DispatcherServlet
        1
    
    
        mvc-dispatcher
        /
    
    
        contextConfigLocation
        /WEB-INF/mvc-dispatcher-servlet.xml
    

    
    
        encodingFilter
        org.springframework.web.filter.CharacterEncodingFilter
        
            encoding
            UTF-8
        
        
            forceEncoding
            true
        
    
    
        encodingFilter
        /v2/api/*
    

    
        org.springframework.web.context.ContextLoaderListener
    

mvc-dispatcher-servlet.xml

这个文件要自己在WEB-INF文件夹下新建

index.html

swagger-ui-2.1.3这个文件夹是从https://github.com/swagger-api/swagger-ui项目中的dist文件夹拷贝过来的，想要最新版可以自己拷贝，还要改之前mvc-dispatcher-servlet.xml中地址转发的文件名
index.html这个文件在swagger-ui-2.1.3文件夹下，只需要改默认的url，该项目在35行左右，改为地址：端口/项目名/v2/api-docs
示例

//          这里填项目地址最后以v2/api-docs结尾
//          因为我是用idea跑的，所以8080/不用加项目名，真正部署是需要加的
        url = "http://localhost:8080/v2/api-docs";

ApplicationSwaggerConfig

这个是swagger2的配置文件

/**
 * Swagger描述
 * 下面两个注解可以让其被spring扫描到
 */
@Configuration
@EnableSwagger2
public class ApplicationSwaggerConfig {

    @Bean
    public Docket configSpringfoxDocketForAll() {
        return new Docket(DocumentationType.SWAGGER_2)
                .produces(Sets.newHashSet("application/json", "application/xml"))
                .consumes(Sets.newHashSet("application/json", "application/xml"))
                .protocols(Sets.newHashSet("http"/*, "https"*/))
                .forCodeGeneration(true)
                .select().paths(regex(".*"))
                .build()
                .apiInfo(apiInfo());
    }

    //页面头部api信息配置
    private ApiInfo apiInfo() {
        ApiInfo apiInfo = new ApiInfo(
                "SpringMVC REST API文档",
                "使用Swagger UI构建SpringMVC REST风格的可视化文档",
                "1.0.0",
                "http://localhost:8080/v2/api-docs",
                "[email protected]",
                "Apache License",
                "http://www.apache.org/licenses/LICENSE-2.0.html"
        );
        return apiInfo;
    }

}

TestController

这个controller用来测试，只展示最简单的用法，详细请看swagger文档

@Api(value = "测试API", description = "测试API")
@RestController
@RequestMapping("/test")
public class TestController {
    @RequestMapping(value = "/hello")
    public String hello(String name) {
        return "hello "+name;
    }

}

效果图

这里写图片描述

完整的代码

https://github.com/jkgeekJack/swagger2-springmvc-example