JavaWeb日记——当springmvc遇上swagger2

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

目录结构

POM

<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
    <modelVersion>4.0.0modelVersion>
    <groupId>com.jkgroupId>
    <artifactId>swagger2-springmvc-exampleartifactId>
    <packaging>warpackaging>
    <version>1.0version>
    <name>SpringMVC Swagger Webappname>
    <url>http://maven.apache.orgurl>

    <properties>
        <springfox-version>2.3.0springfox-version>
        <spring-version>4.2.4.RELEASEspring-version>
        <servlet-api-version>3.1.0servlet-api-version>
    properties>

    <dependencies>
        <dependency>
            <groupId>javax.servletgroupId>
            <artifactId>jstlartifactId>
            <version>1.2version>
        dependency>
        
        <dependency>
            <groupId>com.fasterxml.jackson.coregroupId>
            <artifactId>jackson-databindartifactId>
            <version>2.6.4version>
        dependency>
        <dependency>
            <groupId>org.codehaus.jacksongroupId>
            <artifactId>jackson-mapper-aslartifactId>
            <version>1.9.13version>
        dependency>
        
        <dependency>
            <groupId>org.springframeworkgroupId>
            <artifactId>spring-webmvcartifactId>
            <version>${spring-version}version>
        dependency>
        <dependency>
            <groupId>org.springframeworkgroupId>
            <artifactId>spring-context-supportartifactId>
            <version>${spring-version}version>
        dependency>
        
        <dependency>
            <groupId>io.springfoxgroupId>
            <artifactId>springfox-swagger2artifactId>
            <version>${springfox-version}version>
        dependency>
        <dependency>
            <groupId>javax.servletgroupId>
            <artifactId>javax.servlet-apiartifactId>
            <version>${servlet-api-version}version>
            <scope>providedscope>
        dependency>
    dependencies>

project>

web.xml

<web-app id="WebApp_ID" version="2.4"
         xmlns="http://java.sun.com/xml/ns/j2ee" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee
    http://java.sun.com/xml/ns/j2ee/web-app_2_4.xsd">

    <display-name>Spring Web MVC Applicationdisplay-name>

    
    <servlet>
        <servlet-name>mvc-dispatcherservlet-name>
        <servlet-class>org.springframework.web.servlet.DispatcherServletservlet-class>
        <load-on-startup>1load-on-startup>
    servlet>
    <servlet-mapping>
        <servlet-name>mvc-dispatcherservlet-name>
        <url-pattern>/url-pattern>
    servlet-mapping>
    <context-param>
        <param-name>contextConfigLocationparam-name>
        <param-value>/WEB-INF/mvc-dispatcher-servlet.xmlparam-value>
    context-param>

    
    <filter>
        <filter-name>encodingFilterfilter-name>
        <filter-class>org.springframework.web.filter.CharacterEncodingFilterfilter-class>
        <init-param>
            <param-name>encodingparam-name>
            <param-value>UTF-8param-value>
        init-param>
        <init-param>
            <param-name>forceEncodingparam-name>
            <param-value>trueparam-value>
        init-param>
    filter>
    <filter-mapping>
        <filter-name>encodingFilterfilter-name>
        <url-pattern>/v2/api/*url-pattern>
    filter-mapping>

    <listener>
        <listener-class>org.springframework.web.context.ContextLoaderListenerlistener-class>
    listener>

web-app>

mvc-dispatcher-servlet.xml

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

<beans xmlns="http://www.springframework.org/schema/beans"
       xmlns:context="http://www.springframework.org/schema/context"
       xmlns:mvc="http://www.springframework.org/schema/mvc" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xsi:schemaLocation="
        http://www.springframework.org/schema/beans     
        http://www.springframework.org/schema/beans/spring-beans-4.1.xsd
        http://www.springframework.org/schema/context 
        http://www.springframework.org/schema/context/spring-context-4.1.xsd
        http://www.springframework.org/schema/mvc
        http://www.springframework.org/schema/mvc/spring-mvc-4.1.xsd">
    
    <context:component-scan base-package="com.jk"/>
    
    <mvc:annotation-driven/>
    
    <mvc:resources mapping="/swagger-ui/**" location="WEB-INF/swagger-ui-2.1.3/"/>
    <mvc:resources mapping="index.html" location="WEB-INF/swagger-ui-2.1.3/"/>
    <mvc:redirect-view-controller path="/" redirect-url="index.html"/>
beans>

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