Mybatis+spring+springmvc+swagger

Mybatis+spring+springmvc+swagger

前言
Swagger 是一款RESTFUL接口的文档在线自动生成+功能测试功能软件。本文简单介绍了在项目中集成swagger的方法和一些常见问题。如果想深入分析项目源码，了解更多内容，见参考资料。

Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法，参数和模型紧密集成到服务器端的代码，允许API来始终保持同步。Swagger 让部署管理和使用功能强大的API从未如此简单

一、使用介绍
什么是 Swagger?

Swagger™的目标是为REST APIs 定义一个标准的，与语言无关的接口，使人和计算机在看不到源码或者看不到文档或者不能通过网络流量检测的情况下能发现和理解各种服务的功能。当服务通过Swagger定义，消费者就能与远程的服务互动通过少量的实现逻辑。类似于低级编程接口，Swagger去掉了调用服务时的很多猜测。

• JDK1.7
• Spring 4.0.2
• swagger 2.4

一、依赖管理
在整合之前，需要把所有使用到的依赖包全部引入.
pom.xml

<dependencies>        <dependency>            <groupId>io.springfox</groupId>            <artifactId>springfox-swagger2</artifactId>            <version>2.4.0</version>        </dependency>        <dependency>            <groupId>io.springfox</groupId>            <artifactId>springfox-swagger-ui</artifactId>            <version>2.4.0</version>        </dependency>        <dependency>            <groupId>junit</groupId>            <artifactId>junit</artifactId>            <version>4.11</version>            <!-- 表示开发的时候引入，发布的时候不会加载此包 -->            <scope>test</scope>        </dependency>        <dependency>            <groupId>com.fasterxml.jackson.core</groupId>            <artifactId>jackson-databind</artifactId>            <version>2.7.5</version>        </dependency>        <!-- spring核心包 -->        <dependency>            <groupId>org.springframework</groupId>            <artifactId>spring-core</artifactId>            <version>${spring.version}</version>        </dependency>        <dependency>            <groupId>org.springframework</groupId>            <artifactId>spring-web</artifactId>            <version>${spring.version}</version>        </dependency>        <dependency>            <groupId>org.springframework</groupId>            <artifactId>spring-oxm</artifactId>            <version>${spring.version}</version>        </dependency>        <dependency>            <groupId>org.springframework</groupId>            <artifactId>spring-tx</artifactId>            <version>${spring.version}</version>        </dependency>        <dependency>            <groupId>org.springframework</groupId>            <artifactId>spring-jdbc</artifactId>            <version>${spring.version}</version>        </dependency>        <dependency>            <groupId>org.springframework</groupId>            <artifactId>spring-webmvc</artifactId>            <version>${spring.version}</version>        </dependency>        <dependency>            <groupId>org.springframework</groupId>            <artifactId>spring-aop</artifactId>            <version>${spring.version}</version>        </dependency>        <dependency>            <groupId>org.springframework</groupId>            <artifactId>spring-context-support</artifactId>            <version>${spring.version}</version>        </dependency>        <dependency>            <groupId>org.springframework</groupId>            <artifactId>spring-test</artifactId>            <version>${spring.version}</version>        </dependency>        <!-- mybatis核心包 -->        <dependency>            <groupId>org.mybatis</groupId>            <artifactId>mybatis</artifactId>            <version>${mybatis.version}</version>        </dependency>        <!-- mybatis/spring包 -->        <dependency>            <groupId>org.mybatis</groupId>            <artifactId>mybatis-spring</artifactId>            <version>1.2.2</version>        </dependency>        <!-- 导入java ee jar 包 -->        <dependency>            <groupId>javax</groupId>            <artifactId>javaee-api</artifactId>            <version>7.0</version>        </dependency>        <!-- 导入Mysql数据库链接jar包 -->        <dependency>            <groupId>mysql</groupId>            <artifactId>mysql-connector-java</artifactId>            <version>5.1.30</version>        </dependency>        <!-- 导入dbcp的jar包，用来在applicationContext.xml中配置数据库 -->        <dependency>            <groupId>commons-dbcp</groupId>            <artifactId>commons-dbcp</artifactId>            <version>1.2.2</version>        </dependency>        <!-- JSTL标签类 -->        <dependency>            <groupId>jstl</groupId>            <artifactId>jstl</artifactId>            <version>1.2</version>        </dependency>        <!-- 日志文件管理包 -->        <!-- log start -->        <dependency>            <groupId>log4j</groupId>            <artifactId>log4j</artifactId>            <version>${log4j.version}</version>        </dependency>        <!-- 格式化对象，方便输出日志 -->        <dependency>            <groupId>com.alibaba</groupId>            <artifactId>fastjson</artifactId>            <version>1.1.41</version>        </dependency>        <dependency>            <groupId>org.slf4j</groupId>            <artifactId>slf4j-api</artifactId>            <version>${slf4j.version}</version>        </dependency>        <dependency>            <groupId>org.slf4j</groupId>            <artifactId>slf4j-log4j12</artifactId>            <version>${slf4j.version}</version>        </dependency>        <!-- log end -->        <!-- 映入JSON -->        <dependency>            <groupId>org.codehaus.jackson</groupId>            <artifactId>jackson-mapper-asl</artifactId>            <version>1.9.13</version>        </dependency>        <!-- 上传组件包 -->        <dependency>            <groupId>commons-fileupload</groupId>            <artifactId>commons-fileupload</artifactId>            <version>1.3.1</version>        </dependency>        <dependency>            <groupId>commons-io</groupId>            <artifactId>commons-io</artifactId>            <version>2.4</version>        </dependency>        <dependency>            <groupId>commons-codec</groupId>            <artifactId>commons-codec</artifactId>            <version>1.9</version>        </dependency>    </dependencies>

spring.xml

    <!-- 扫描数据源文件 -->    <context:property-placeholder location="classpath:config/jdbc.properties" />    <!-- 自动将Service层注入 -->    <context:component-scan base-package="cn.easyframework.service.impl" />    <!-- dbcp数据源 -->    <bean id="datasource" class="org.apache.commons.dbcp.BasicDataSource">        <property name="driverClassName" value="${jdbc.driver}" />        <property name="url" value="${jdbc.url}" />        <property name="username" value="${jdbc.username}" />        <property name="password" value="${jdbc.password}" />    </bean>    <!-- 创建session工厂扫描mapper.xml文件 -->    <bean id="sqlSessionFactory" class="org.mybatis.spring.SqlSessionFactoryBean">        <property name="dataSource" ref="datasource" />        <property name="mapperLocations" value="classpath*:cn/easyframework/persist/*/*.xml" />        <property name="configLocation" value="classpath:config/mybatis-config.xml"></property>    </bean>    <!-- dao接口所在包名，Spring会自动查找其下的类 -->    <bean class="org.mybatis.spring.mapper.MapperScannerConfigurer">        <property name="basePackage" value="cn.easyframework.persist" />        <property name="sqlSessionFactoryBeanName" value="sqlSessionFactory" />    </bean>    <!-- 事务管理 -->    <bean id="transactionManager"        class="org.springframework.jdbc.datasource.DataSourceTransactionManager">        <property name="dataSource" ref="datasource" />    </bean>    <tx:advice id="txAdvice" transaction-manager="transactionManager">        <tx:attributes>            <tx:method name="insert*" propagation="REQUIRED" />            <tx:method name="add*" propagation="REQUIRED" />            <tx:method name="save*" propagation="REQUIRED" />            <tx:method name="update*" propagation="REQUIRED" />            <tx:method name="change*" propagation="REQUIRED" />            <tx:method name="move*" propagation="REQUIRED" />            <tx:method name="submit*" propagation="REQUIRED" />            <tx:method name="distribute*" propagation="REQUIRED" />            <tx:method name="delete*" propagation="REQUIRED" />            <tx:method name="cancel*" propagation="REQUIRED" />            <tx:method name="*" propagation="SUPPORTS" />        </tx:attributes>    </tx:advice>

springMVC.xml

    <!--要扫描的包 -->    <context:component-scan base-package="cn.easyframework.web" />    <!-- 启用注解 -->    <mvc:default-servlet-handler />    <!-- 加载静态资源 -->    <mvc:annotation-driven />    <!-- 加载swagger配置类 -->    <bean class="com.easyframework.swagger.SwaggerConfig"/>    <mvc:resources mapping="/swagger/**" location="/swagger/" />      <!--视图解析器 -->    <bean        class="org.springframework.web.servlet.view.InternalResourceViewResolver">        <property name="prefix" value="/WEB-INF/view/" />        <property name="suffix" value=".jsp" />    </bean>    <bean id="multipartResolver"        class="org.springframework.web.multipart.commons.CommonsMultipartResolver">        <property name="maxUploadSize" value="104857600" />        <property name="maxInMemorySize" value="4096" />        <property name="defaultEncoding" value="UTF-8"></property>    </bean>

二、Swagger配置
  Swagger的配置实际上就是自定义一个Config类，通过java编码的方式实现配置。代码如下：
  
 SwaggerConfig.java

package com.easyframework.swagger;import org.springframework.context.annotation.Bean;  import org.springframework.context.annotation.ComponentScan;  import org.springframework.context.annotation.Configuration;  import org.springframework.web.servlet.config.annotation.EnableWebMvc;  import org.springframework.web.servlet.config.annotation.WebMvcConfigurationSupport;  import springfox.documentation.builders.ApiInfoBuilder;  import springfox.documentation.builders.PathSelectors;  import springfox.documentation.builders.RequestHandlerSelectors;  import springfox.documentation.service.ApiInfo;import springfox.documentation.service.Contact;import springfox.documentation.spi.DocumentationType;  import springfox.documentation.spring.web.plugins.Docket;  import springfox.documentation.swagger2.annotations.EnableSwagger2;  /*  * Restful API 访问路径: * swagger-ui.html文件的访问路径（http://localhost:8080/项目名称/v2/api-docs） */ @EnableWebMvc@EnableSwagger2 //使swagger2生效   @ComponentScan(basePackages = { "cn.easyframework.web" })//需要扫描的包路径  @Configuration //配置注解，自动在本类上下文加载一些环境变量信息    public class SwaggerConfig extends WebMvcConfigurationSupport {    @Bean    public Docket customImplementation() {        return new Docket(DocumentationType.SWAGGER_2)                  .apiInfo(apiInfo())                  .select()                  .apis(RequestHandlerSelectors.basePackage("cn.easyframework.web"))                 .paths(PathSelectors.any())                .build();      }     private ApiInfo apiInfo() {              return new ApiInfoBuilder()                      .title("接口文档")                      // .termsOfServiceUrl("http://blog.csdn.net/he90227")                      .contact(new Contact("LiTong", "", ""))                    .version("1.1")                      .build();          }  }

三、Swagger-UI配置
Swagger扫描解析得到的是一个json文档，对于用户不太友好。下面介绍swagger-ui，它能够友好的展示解析得到的接口说明内容。

  从https://github.com/swagger-api/swagger-ui 获取3.0版本以下，2.0版本以上。其所有的 dist 目录下东西放到需要集成的项目里，本文放入 src/main/webapp/WEB-INF/swagger/ 目录下。

  修改swagger/index.html文件，默认是从连接（http://localhost:8080/项目名称/v2/api-docs）获取 API 的 JSON，比如我的url值为：http://localhost:8080/easyframework-web/v2/api-docs

  因为swagger-ui项目都是静态资源，restful形式的拦截方法会将静态资源进行拦截处理，所以在springmvc配置文件中需要配置对静态文件的处理方式。

//所有swagger目录的访问，直接访问location指定的目录

最后将swagger目录下的index.html文件名称修改为swagger-ui.html
四、Swagger注解 代码如下：

@RestController@RequestMapping(value="/findUser")public class AppUserController {    @Autowired    private AppUserService appUserService;    @ApiOperation(value = "获取用户列表",httpMethod = "GET",notes = "获取对象集合")      @RequestMapping(value="/findAll",method=RequestMethod.GET,produces = {"application/json; charset=utf-8"})    public  List<AppUser> findAll(){        List<AppUser> appUsers = appUserService.findAll();        return appUsers;    }    @ApiOperation(value = "根据id获取对象用户",httpMethod = "GET",response=AppUser.class,notes="按照id查询用户")      @RequestMapping(value="/findByid/{id}",method=RequestMethod.GET,produces = {"application/json; charset=utf-8"})    public  AppUser findByid(@PathVariable Long id){        AppUser appUser = appUserService.findByid(id);        return appUser;    }    @ApiOperation(value="添加用户信息",httpMethod="post",response=Long.class,notes="返回自增列")    @RequestMapping(value="/saveAppUser",method=RequestMethod.POST,produces = {"application/json; charset=utf-8","text/plain;charset=utf-8"})    public Long saveAppUser(@RequestBody AppUser appUser){        Long result=appUserService.saveAppUser(appUser);        return result;    }    @ApiOperation(value="根据ID删除用户信息",httpMethod="get",response=Long.class,notes="根据ID删除用户信息")    @RequestMapping(value="/delAppUser/{id}",method=RequestMethod.GET,produces = {"application/json; charset=utf-8"})    public Long delAppUser(@PathVariable Long id){        Long result=appUserService.delAppUser(id);        return result;    }

上述代码是Controller中的一个方法，@ApiOperation注解对这个方法进行了说明，@ApiParam注解对方法参数进行了说明。关于这两个注解的使用，可以参看源码。这样子，Swagger就可以扫描接口方法，得到我们自定义的接口说明内容。

 说明：  其中@ApiOperation和@ApiParam为添加的API相关注解，个参数说明如下：  @ApiOperation(value = “接口说明”, httpMethod = “接口请求方式”, response = “接口返回参数类型”, notes = “接口发布说明”；其他参数可参考源码；  @ApiParam(required = “是否必须参数”, name = “参数名称”, value = “参数具体描述”

打开浏览器直接访问swagger目录下的swagger-ui.html文件，即可看到接口文档说明了。注意访问地址哦！看下图：