SpringMVC整合Swagger2

       swagger，丝袜哥，中文“拽”的意思。它是一个功能强大的api框架，它的集成非常简单，不仅提供了在线文档的查阅，而且还提供了在线文档的测试。另外swagger很容易构建restful风格的api，简单优雅帅气，正如它的名字。

依赖管理

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.7.0</version>
</dependency>

swagger配置

swagger的配置其实就是自定义一个config类。通过java编码实现。

package com.xxx.xxx.config;

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 springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

/**
 * Created by songhairui on 2016/11/16.
 * @Configuration:让spring加载该类配置
 * @EnableSwagger2:启用swagger
 * @EnableWebMvc:启用MVC
 * @ComponentScan:设置需要扫描的包，基本是swagger注解所在的包，例如Controller
 */
@Configuration
@EnableSwagger2
@EnableWebMvc
@ComponentScan("com.xxx.xxx.web")
public class Swagger2Config {

    @Bean
    public Docket createRestApi(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo()).select()
                .apis(RequestHandlerSelectors.basePackage("com.xxx.xxx.web"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("服务端 RESTFul Apis")
                .description("服务端 RESTFul Apis")
                .version("3.1.0")
                .build();
    }


}

先来段代码练练手

/**
 * 根据用户名获取用户对象
 * @param name
 * @return
 */
@RequestMapping(value="/name/{name}", method = RequestMethod.GET)
@ResponseBody
@ApiOperation(value = "根据用户名获取用户对象", httpMethod = "GET", response = ApiResult.class, notes = "根据用户名获取用户对象")
public ApiResult getUserByName(@ApiParam(required = true, name = "name", value = "用户名") @PathVariable String name) throws Exception{
    UcUser ucUser = ucUserManager.getUserByName(name);

    if(ucUser != null) {
        ApiResult<UcUser> result = new ApiResult<UcUser>();
        result.setCode(ResultCode.SUCCESS.getCode());
        result.setData(ucUser);
        return result;
    } else {
        throw new BusinessException("根据{name=" + name + "}获取不到UcUser对象");
    }
}

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

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

swagger-UI配置

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

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

  修改swagger/index.html文件，默认是从连接http://petstore.swagger.io/v2/swagger.json获取 API 的 JSON，这里需要将url值修改为http://{ip}:{port}/{projectName}/api-docs的形式，{}中的值根据自身情况填写。比如我的url值为：/v2/api-docs

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

   //所有swagger目录的访问，直接访问location指定的目录
   <mvc:resources mapping="/swagger/**" location="/swagger/"/>

  

OK！大功告成，打开浏览器直接访问http://localhost:8080/posfront-api-docs.html，即可看到接口文档说明了。注意访问地址哦！看下图：

参考资料

更汉化的接口管理工具 sosoapi

swagger 官网注解

一牛人的：汉化的swagger-ui组件