SpringBoot集成springfox-swagger2构建

参考自：https://blog.csdn.net/u014231523/article/details/54562695

1. POM引用相关依赖

<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>

2. 创建swagger配置类

package com.xxx.xxx.core.common.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
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;

@Configuration
public class SwaggerConfig {

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

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("XXX平台API文档")
                .description("XXX平台API文档")
                .termsOfServiceUrl("http://yourTermsOfService.com")
                .version("1.0")
                .build();
    }
}

启动服务后，这时候可以查看以下地址
swagger会显示已填写的title，description等信息。
${port}为application.properties中设置的端口号(如果不设置，默认为8080)

http://${ip}:${port}/swagger-ui.html#/

3. 在自己的Controller添加相关的注解

1. 原来的Controller类上使用的@controller，现在可以使用@RestController代替
2. 方法的@ResponseBody可以不用写了，因为版本在4.0.1之后的@RestController的注解接口上已经添加了。

@Target(ElementType.TYPE)
@Retention(RetentionPolicy.RUNTIME)
@Documented
@Controller
@ResponseBody
public @interface RestController {

    /**
     * The value may indicate a suggestion for a logical component name,
     * to be turned into a Spring bean in case of an autodetected component.
     * @return the suggested component name, if any
     * @since 4.0.1
     */
    String value() default "";
}

常用的注解如下： 
- @Api()用于类名 
- @ApiOperation()用于方法名 
- @ApiParam()用于参数说明 
- @ApiModel()用于实体类 
- @ApiModelProperty用于实体类属性 
更加详细的含义可以参考官方说明wiki 

这里会把相应包下的所有controller按类进行显示。
我们看下一些例子（请忽略业务逻辑，只看注解）

1. Get的例子

@RequestMapping("/hotline")
@RestController
@Api(tags = "热点线路统计分析接口")
public class HotLineController {
    @ApiResponses(value = { @ApiResponse(code = 500, message = "系统错误"),
                            @ApiResponse(code = 200, message = "0 成功,其它为错误") })
    @ApiOperation(httpMethod = "GET", value = "获取热度前10条线路")
    @RequestMapping(method = RequestMethod.GET, value = "/getTop10Lines")
    public SimpleResponse<List<GroundHotLine>> getTop10Lines() {
        //逻辑略
    }
}

2. Post的例子

@RequestMapping("/adas_alarm")
@RestController
@Api(tags = "ADAS告警接口")
public class AdasAlarmController {
    @ApiResponses(value = { @ApiResponse(code = 500, message = "系统错误"),
                            @ApiResponse(code = 200, message = "0 成功,其它为错误") })
    @ApiOperation(httpMethod = "POST", value = "查询adas告警统计数据(司机纬度)")
    @RequestMapping(method = RequestMethod.POST, value = "/querySummaryByDriver")
    public SimpleResponse<Page<AdasAlarmSummaryByDriver>> querySummaryByDriver(
            @RequestBody @ApiParam(value = "查询参数", required = true) AdasAlarmDriverCond queryParams) {
        //逻辑略
    }
}

使用对象作为参数时，可以在对象上添加相应的注解，用户页面显示
PS：这里还用到lombok.Data注解，省略Getter和Setter

1. 参数for Post

import lombok.Data;

@Data
public class AdasAlarmDriverCond {
    @ApiModelProperty(value = "司机名称")
    private String driverName;

    @ApiModelProperty(value = "司机工号")
    private String driverEmpCode;

    // 是否支持分页逻辑 目的用于分页和丰分页的区分
    @ApiModelProperty(hidden = true)
    private String pageFlag;
}

2. 参数for说明required=true（用于Get）

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;

import java.util.List;

@ApiModel(description="用户对象user")
public class User {
    @ApiModelProperty(value="用户名",name="username")
    private String username;
    @ApiModelProperty(value="状态",name="state",required=true)
    private Integer state;
    private String password;

    public String getUsername() {
        return username;
    }
    public void setUsername(String username) {
        this.username = username;
    }

    public Integer getState() {
        return state;
    }
    public void setState(Integer state) {
        this.state = state;
    }

    public String getPassword() {
        return password;
    }
    public void setPassword(String password) {
        this.password = password;
    }
}

如果在字段(如：state)上添加注释

@ApiModelProperty(required=true)

那么在swagger前端上做调用/测试时就是必填（默认是false）