spring boot 集成 swagger2 并定制RestFul API接口

1、添加maven依赖：

<dependency>
	<groupId>io.springfox</groupId>
	<artifactId>springfox-swagger2</artifactId>
	<version>2.2.2</version>
</dependency>
<dependency>
	<groupId>io.springfox</groupId>
	<artifactId>springfox-swagger-ui</artifactId>
	<version>2.2.2</version>
</dependency>

2、添加配置

@Configuration
@EnableSwagger2
public class Swagger2 {

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

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("省钱小工具项目接口文档")
                .description("利用 爬虫等技术构建基于分布式架构下的 api")
                .termsOfServiceUrl("http://www.chaojilaji.com/")
                .contact("chaojilaji")
                .version("1.0")
                .build();
    }
}

3、文档学习
注解：http://docs.swagger.io/swagger-core/v1.5.X/apidocs/index.html?io/swagger/annotations/ApiResponses.html

demo：

@ApiOperation(value="创建用户", notes="用户注册")
@ApiImplicitParams({
        @ApiImplicitParam(name = "username", value = "用户名", required = true, dataType = "String"),
        @ApiImplicitParam(name = "password", value = "密码", required = true, dataType = "String"),
        @ApiImplicitParam(name = "phone", value = "电话号码", required = true, dataType = "String")
})

为了使返回值的model内有值，需要把返回值也定义成类的格式，比如pojo。

public class UserResponce {
    private String info;
    private int code;
    private String key;

    public String getInfo() {
        return info;
    }

    public int getCode() {
        return code;
    }

    public String getKey() {
        return key;
    }

    public void setInfo(String info) {
        this.info = info;
    }

    public void setCode(int code) {
        this.code = code;
    }

    public void setKey(String key) {
        this.key = key;
    }
}
//修改controller
public UserResponce userLogin(@RequestParam("phone") final String phone,
                                         @RequestParam("password") final String password,
                                         @RequestParam("ip") final String ip){
        UserResponce ans = new UserResponce();
        // TODO: 2018/12/18 验证该phone是否已经登录，不能直接根据这个token是否存在，应该判断时间
        String token = redisService.getTokenFromRedis(phone);
        if (token != ""){
            if (jwtService.checkTimeFromToken(token, ip)){
                ans.setCode(300);
                ans.setInfo("用户已经登录，请半小时后重新尝试");
                return ans;
            }
        }
        UserInfoDto dto = userInfoService.getUser(phone);
        if (!dto.isRegister()){
            dto.setPassword(password);
            UserInfoDto dto1 = userInfoService.checkPassword(dto);
            if (dto1.isVoladate()){
                String key = jwtService.getJwtsString(ip);
                ans.setCode(200);
                ans.setInfo("成功");
                ans.setKey(key);
                // TODO: 2018/12/18 将key放入redis
                redisService.insertTokenTORedis(key,phone);
                return ans;
            }
        }
        ans.setCode(400);
        ans.setInfo("用户名或密码错误");
        return ans;
    }

使用限制没啥问题了，不过需要解决的是，当项目上线了，如果避免别人访问
解决办法：
使用注解@ConditionalOnProperty(name = “swagger.enable”, havingValue = “true”) 然后在测试配置或者开发配置中 添加 swagger.enable = true 即可开启，生产环境不填则默认关闭Swagger.

@Configuration
@EnableSwagger2
@ConditionalOnProperty(name = "swagger.enable", havingValue = "true")
public class Swagger2 {

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

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("ccs 接口文档")
                .description("Copyright © 2018 重庆市信息通信咨询设计院有限公司版权所有")
                .termsOfServiceUrl("http://www.cqcdi.com/")
                .contact("chaojilaji")
                .version("1.0")
                .build();
    }
}

然后在配置文件中加入：

swagger.enable=true

将不规范的返回值设置成json：
@ApiResponce中有一个可选项 responseContainer,解释是：Declares a container wrapping the response.
Valid values are “List”, “Set” or “Map”. Any other value will be ignored.感兴趣的同学可以自己尝试一下，对于那种接口写得各种奇怪的类型（比如一个Int值，一个Map，怎么做swagger才能进行显示）