springMvc+swagger整合例子

　　Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法，参数和模型紧密集成到服务器端的代码，允许API与接口方法，参数等保存同步，大大减少了接口开发人员的工作量.这个例子是我本地运行正常的，完整demo在文章最后。

　　第一步：在pom.xml引入相关jar

<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>com.fasterxml.jackson.core</groupId>
            <artifactId>jackson-core</artifactId>
            <version>2.8.0</version>
        </dependency>
        <dependency>
            <groupId>com.fasterxml.jackson.core</groupId>
            <artifactId>jackson-databind</artifactId>
            <version>2.6.3</version>
        </dependency>
        <dependency>
            <groupId>com.fasterxml.jackson.core</groupId>
            <artifactId>jackson-annotations</artifactId>
            <version>2.6.3</version>
        </dependency>  

　　第二步：配置spring-servlet.xml

<!-- 激活@controller模式 -->
    <mvc:annotation-driven />
    <!-- 配置包扫描位置（会在此包下扫描@controller控制器） -->
    <context:component-scan base-package="com.scan,com.bean" />
<!--  swagger静态文件路径 -->
<mvc:resources mapping="/swagger/**" location="/WEB-INF/swagger/" cache-period="31556926"/>
    <mvc:default-servlet-handler />
    <bean class="com.scan.config.SwaggerConfig" /> 

　　第三步：编写SwaggerConfig

　　　　

package com.scan.config;

import com.google.common.base.Predicate;

import org.springframework.beans.factory.annotation.Autowired;
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.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;

import java.util.List;

import static com.google.common.base.Predicates.or;
import static com.google.common.collect.Lists.newArrayList; 

@Configuration
@EnableSwagger2
@ComponentScan(basePackages = {"com.scan.controller"})
@EnableWebMvc
public class SwaggerConfig extends WebMvcConfigurationSupport {

    @Bean
    public Docket customDocket() {
        //
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo());
    }

    private ApiInfo apiInfo() {
        Contact contact = new Contact("老王", "https://www.baidu.me", "baidu_666@icloud.com");
        return new ApiInfo("Blog前台API接口",//大标题 title
                "Swagger测试demo",//小标题
                "0.0.1",//版本
                "www.baidu.com",//termsOfServiceUrl
                contact,//作者
                "Blog",//链接显示文字
                "https://www.baidu.me"//网站链接
        );
    }

}

　　第四步：控制层的配置

　　

@Controller
@RequestMapping("/userController")
@Api(tags = "二：用户信息") //swagger分类标题注解
public class UserController {

    @RequestMapping(value = "/listCompound", method = RequestMethod.GET)
    @ResponseBody
　　//swagger返回值注解
    @ApiResponses(value = {
            @ApiResponse(code = 500, message = "系统错误"),
            @ApiResponse(code = 200, message = "0 成功,其它为错误,返回格式：{code:0,data[{}]},data中的属性参照下方Model", response = UserVo.class) })
    @ApiOperation(httpMethod = "GET", value = "个人信息")//swagger 当前接口注解
    public String listCompound(
            @ApiParam(required = true, name = "start", value = "start") int start,
            int limit,
            @ApiParam(required = false, name = "userName", value = "名称模糊查询") String userName) {
        List<UserVo> data = new ArrayList<UserVo>();
        String msg = data.size() > 0 ? "" : "没有查询到相关记录";
        Result result = new Result();
        result.setMsg(msg);
        result.setCode(0);
        result.setData(data);
        return JSONObject.toJSONString(result);
    }

　　第五步：下载swaggerUi,将下载后的文件解压，将dist目录下的文件，复制到webapp下的swagger目录中(这个目录的名字自定义，但要和spring-servert.xml中(<mvc:resources mapping="/swagger/**" location="/WEB-INF/swagger/") 的名称要一致,修改index.html中文档加载的地址.

window.onload = function() {

  // Build a system
  const ui = SwaggerUIBundle({
    //url: "http://petstore.swagger.io/v2/swagger.json",
    url:"http://127.0.0.1:8080/swagger-spring/v2/api-docs.do",
    dom_id: '#swagger-ui',
    deepLinking: true,
    presets: [
      SwaggerUIBundle.presets.apis,
      SwaggerUIStandalonePreset
    ],
    plugins: [
      SwaggerUIBundle.plugins.DownloadUrl
    ],
    layout: "StandaloneLayout"
  })

　　如果以上配置正确，在浏览器中输入http://127.0.0.1:8080/swagger-spring/swagger/index.html，将会出现如下界面:

　　

　swagger注解说明

　　 1、与模型相关的注解,用在bean上面

　　　　@ApiModel：用在bean上，对模型类做注释；

　　　　@ApiModelProperty：用在属性上，对属性做注释

　　2、与接口相关的注解

　　　　@Api：用在controller上，对controller进行注释；

　　　　@ApiOperation：用在API方法上，对该API做注释，说明API的作用；

　　　　@ApiImplicitParams：用来包含API的一组参数注解，可以简单的理解为参数注解的集合声明； 

　　　　@ApiImplicitParam：用在@ApiImplicitParams注解中，也可以单独使用，说明一个请求参数的各个方面，该注解包含的常用选项有：

　　　　　　paramType：参数所放置的地方，包含query、header、path、body以及form，最常用的是前四个。

　　　　　　name：参数名；

　　　　　　dataType：参数类型，可以是基础数据类型，也可以是一个class；

　　　　　　required：参数是否必须传；

　　　　　　value：参数的注释，说明参数的意义；

　　　　　　defaultValue：参数的默认值；

　　　　

　　　 @ApiResponses：通常用来包含接口的一组响应注解，可以简单的理解为响应注解的集合声明；

　　　 @ApiResponse：用在@ApiResponses中，一般用于表达一个响应信息

　　　　　　code：即httpCode，例如400 

　　　　　　message：信息，例如"操作成功"

　　　　　　response = UserVo.class  这里UserVo是一个配置了@ApiModel注解的对像，该是对像属性已配置 @ApiModelProperty,swagger可以通过这些配置，生　成接口返回值

　　

　　注意事项:

1. 为了在swagger-ui上看到输出，至少需要两个注解：@Api和@ApiOperation
2. 即使只有一个@ApiResponse，也需要使用@ApiResponses包住
3. 对于@ApiImplicitParam的paramType：query、form域中的值需要使用@RequestParam获取， header域中的值需要使用@RequestHeader来获取，path域中的值需要使用@PathVariable来获取，body域中的值使用@RequestBody来获取，否则可能出错；而且如果paramType是body，name就不能是body，否则有问题，与官方文档中的“If paramType is "body", the name should be "body"不符。

　　完整demo下载地址:https://github.com/jlq023/spring_swaggerDemo