SpringBoot+Swagger2 整合

SpringBoot+Swagger2四步整合

第一步：添加相关依赖

<parent>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-parent</artifactId>
<version>1.5.9.RELEASE</version>
</parent><properties>
<swagger2.version>2.7.0</swagger2.version>
</properties><dependencies>
<!--springBoot 相关依赖-->
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-web</artifactId>
</dependency>
<!--swagger2 相关依赖-->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>${swagger2.version}</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>${swagger2.version}</version>
</dependency></dependencies>


创建SrpingBoot启动类

/**
* Springboot+Swagger整合启动类
*
* @author Y.yang
* @date 2019/3/12
*/
@SpringBootApplication
public class SwaggerApplication {public static void main(String[] args) {
SpringApplication.run(SwaggerApplication.class, args);
}
}

第二步：配置Swagger2

注意添加@Configuration EnableSwagger2注解

/**
* Swagger2 接口Api文档 配置文件
*
* @author Y.yang
* @date 2019/3/12
*/
@Configuration
@EnableSwagger2
public class SwaggerConfig { /**
* 初始化创建Swagger Api
*/
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
// 详细信息定制
.apiInfo(apiInfo())
.select()
// 指定当前包路径
.apis(RequestHandlerSelectors.basePackage("com.fame.controller"))
// 扫描所有 .apis(RequestHandlerSelectors.any())
.paths(PathSelectors.any())
.build();
}/**
* 添加摘要信息
*/
private ApiInfo apiInfo() {
// 用ApiInfoBuilder进行定制
return new ApiInfoBuilder()
.title("标题：springBoot-Swagger2整合学习")
.description("描述：文档构建器")
.contact(new Contact("Fame-springBoot-Swagger2", null, null))
.version("版本号: 1.0")
.build();
}
}

springfox为我们提供了一个Docket（摘要的意思）类，我们需要把它做成一个Bean注入到spring中，

显然，我们需要一个配置文件，并通过一种方式（显然它会是一个注解）告诉程序，这是一个Swagger配置文件。

springfox允许我们将信息组合成一个ApiInfo的类，作为构造参数传给Docket（当然也可以不构造这个类，而直接使用null，但是你的这个API就太low了）。

第三步：创建测试实例

/**
* Swagger接口测试
*
* @author Y.yang
* @date 2019/3/12
*/
@RestController
public class UserController { @GetMapping("/get")
public String get(){
return "Hello Swagger2";
}
}


第四步：输入SwaggerUI地址

http://localhost:8080/swagger-ui.html

Swagger2基本使用-常用注解

接口/方法常用注解

/**
* Swagger接口测试
*
* @author Y.yang
* @date 2019/3/12
*/
@Api(value = "用户信息", tags = { "用户信息" })
@RestController
public class UserController {@ApiOperation(value = "用户信息分页查询")
@GetMapping("/page")
public String page(User user) {
return "Hello Swagger2";
}@ApiOperation(value = "用户信息查询")
@ApiImplicitParams({
@ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "Integer"),
@ApiImplicitParam(name = "file", value = "文件导入", required = true, dataType = "MultipartFile")
})
@GetMapping("/id")
public UserVo getUser(Long id, MultipartFile file) {
return new UserVo();
}
}


@Api: 描述类/接口的主要用途

用于类；表示标识这个类是swagger的资源

tags–表示说明

value–也是说明，不会显示在接口文档上，可以使用tags替代

但是tags如果有多个值，会生成多个list

@Api(value = "用户信息", tags = { "用户信息" })


@ApiOperation: 描述方法用途

@ApiOperation(value = "用户信息分页查询")


@ApiImplicitParam: 描述方法的参数

@ApiImplicitParams: 描述方法的参数(Multi-Params)

@ApiImplicitParams({
@ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "Integer"),
@ApiImplicitParam(name = "file", value = "文件导入", dataType = "MultipartFile")
})


实体类常用注解

/**
* 用户信息 数据传输对象 Dto（Data Transfer Object）
*
* @author Y.yang
* @date 2019/3/29
*/
@ApiModel(description = "用户信息请求对象")
@Data
public class User implements Serializable {private static final long serialVersionUID = -6986638131456347054L;@ApiModelProperty(value = "姓名")
private String username;@ApiModelProperty(value = "性别")
private String sex;@ApiModelProperty(value = "年龄")
private Integer age;}

@ApiModel:描述实体类（Dto、Vo、Do等）

@ApiModel(description = "用户信息请求对象")

@ApiModelProperty：描述实体类的字段

@ApiModelProperty(value = "姓名")