SpringBoot整合Swagger2

Swagger2

拓展内容

1.为什么要导入数据库驱动包
jdbc就是sum公司提供的一个接口，他不能直接操作数据库，因此需要接口的实现类，而MySQL的驱动就是jdbc的实现类
2. 什么是数据库服务器
服务器就是一台pc机，数据库服务器就是在我们的pc机上安装上我们数据库服务的软件就变成了数据库服务器，数据库的数据存储在硬盘上
3. select * from user 完成了什么事情
 1. 发送SQL语句到数据库服务器
 2.服务器接受到SQL语句
 3.把SQL语句翻译成我们Mysql能够识别的语言
 4.运行翻译后的文件
 5.将结果返回到我们的服务器

1. 什么是Swagger2

官方：Swagger是一个规范的，完整的框架，这个框架的主要功能是生成，描述，调用和可视化的Restful风格的服务。

2.前后端分离存在的一些问题

当手机端和服务器端开发 同步进行的时候，一定要有一个东西来约束开放的双方
东西： 就是一个文档（这个文档的主要共能就是告诉手机端，每一个手机页面需要的数据怎么来服务器端进行请求）
服务端---客户端 怎么来获取数据
接口文档里面就是获取数据的所有接口的说明
接口文档：接口(一个Contoller的请求地址)
接口的要素：
	1. 请求地址
	2.请求的方法(get/post)
	3.请求参数的格式(JSON)
	4.请求的参数中，数据的含义
	5.返回数据的格式
	6.返回数据中参数的含义
无数个接口，整合起来形成一个文档：接口文档

3.Swagger2到底是什么？

这个东西简单来说，就是将我们写的这个接口自动生成文档 以及测试环境

4. Swagger2中的一些组件

Swagger是一个开源的项目
Swagger-tools: 主要存放的是和Swagger集成和整合的工具
Swagger-core：主要就是整个Swagger的核心
Swagger-js：主要是用在JavaScript上的Swagger实现
Swagger-ui：Swagger自动生成文档的这一部分Api

5. Swagger的第一个程序

5.1 导包

		<!--导入swagger 包-->
		<dependency>
			<groupId>io.springfox</groupId>
			<artifactId>springfox-swagger2</artifactId>
			<version>2.7.0</version>
		</dependency>
		<!--导入生成接口文档的包-->
		<dependency>
			<groupId>io.springfox</groupId>
			<artifactId>springfox-swagger-ui</artifactId>
			<version>2.7.0</version>
		</dependency>

5.2 编写配置文件

@SpringBootConfiguration
@EnableSwagger2
//通过扫描包来对api进行监控
public class AppConfig {

    @Bean
    public Docket docket(){
        return new Docket(DocumentationType.SWAGGER_2)
        .apiInfo(apiInfo()) //这个方法的作用(生成接口的时候，页面显示的信息)
        .select() //这个方法的作用是选择哪些路径和api生成接口文档
        .apis(RequestHandlerSelectors.basePackage("com.wcc.springboot.controller"))  //告诉他扫描的接口存在的这个包
        .paths(PathSelectors.any()) //对所有的api进行监控
        .build();
    }
/*
* 这个方法的作用就是生成页面显示的信息
* */
    public ApiInfo apiInfo(){
        return new ApiInfoBuilder()
        .title("swagger2测试") //文档的标题
        .description("×××××测试用的") //文档的描述
        .contact("小王子")  //文档的作者
        .version("1.0")  //文档的版本
        .build();
    }
}
// 除了通过扫描包对api进行监控外，也可以通过对指定路径的api进行监控

@EnableSwagger2
@Configuration
public class SwaggerConfig {

    @Bean
    public Docket docket(){
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("内部接口")
                .apiInfo(apiInfo())
                .select()
                .paths(Predicates.and(PathSelectors.regex("/cla/.*")))
                .build();
    }

    private ApiInfo apiInfo () {
        return new ApiInfoBuilder()
                .version("1.0")
                .title("jiekouceshi")
                .build();
    }
}

5.3 测试

http://127.0.0.1:8080/swagger-ui.html (在浏览器输入这个)

6.Swagger没有参数的测试

6.1 编写结果类

@Data
@AllArgsConstructor
@NoArgsConstructor
public class ResultController<T> {
    private int state;
    private String msg;
    private T data;
}

6.2 编写Controller

@RestController
@Api(value = "user控制器",tags = "user控制器")//给一个标签
public class UserController {

    @RequestMapping(value = "test01",method = RequestMethod.GET)
    @ApiOperation(value = "没有参数的测试") //给本方法的一个说明
   public ResultController<String> test(){
       ResultController<String> result = new ResultController();
       result.setData("我是小王子");
       result.setMsg("请求成功");
       result.setState(1);
      return result;
   }
}

7. Swagger传递简单参数

@RequestMapping(value = "test02",method = RequestMethod.GET)
@ApiOperation(value = "这是传递一个参数的测试",notes = "调用当前方法注意的事项")
@ApiImplicitParam(paramType = "query",name = "userName",value = "用户名",required = true,dataType = "String")
/*ApiImplicitParam中参数的说明
	paramType 类型 数据放在那里的问题
			 header：请求的数据放在请求头里面的 就 用这个类型
			 query：请求的参数 放到了请求地址上 、配套的（@requestParam）
			 path：（RestFul中用于面向资源编程的获取数据的方式），配套的获取数据的注解 @PathVarible
	name： 说明的参数的名字是什么 (如果传递一个参数的话，这三个参数的名称相同)
	value： 当前参数的含义
	required： 当前参数是否必须传入
	dataType：当前参数的类型
*/
    public ResultController<String> test02(@RequestParam("userName")String userName){
        ResultController<String> result = new ResultController();
        result.setData("我是小王子"+userName);
        result.setMsg("请求成功");
        result.setState(1); 
        return result;
    }

8.Swagger传递多个参数

@RequestMapping(value = "test03",method = RequestMethod.GET)
@ApiOperation(value = "这是传递多个参数的测试")
@ApiImplicitParams({
            @ApiImplicitParam(paramType = "query",name = "userName",value = "用户名",required = true,dataType = "String"),
            @ApiImplicitParam(paramType = "query",name = "password",value = "密码",required = true,dataType = "String")
    })
public ResultController<String> test03(@RequestParam("userName")String 		 	  userName,@RequestParam("password")String password){
        ResultController<String> result = new ResultController();
        result.setData("我是小王子"+userName+"----"+password);
        result.setMsg("请求成功");
        result.setState(1);
        return result;
    }

9. 传递对象

9.1 对象的实体类

@Data
@AllArgsConstructor
@NoArgsConstructor
@ApiModel(value = "用户对象")
public class User {
    @ApiModelProperty(value = "用户id")
    private int id;
    @ApiModelProperty(value = "用户名")
    private String name;
    @ApiModelProperty(value = "密码")
    private String pass;
}

9.2 编写controller

@RequestMapping(value = "test04",method = RequestMethod.POST)
@ApiOperation(value = "这是测试用户对象的")
public ResultController<User> test04( @RequestBody User user){
    ResultController<User> result = new ResultController<>();
    result.setState(0);
    result.setMsg("success");
    result.setData(user);
    return result;
}

10. 传递token

什么是token：
用户身份的唯一标识(字符串)

@RequestMapping(value = "test05",method = RequestMethod.POST)
@ApiOperation(value = "这是测试token的")
@ApiImplicitParam(paramType = "header",name="token",value = "用户身份验证",required = true,dataType = "String")
public ResultController<User> test05( @RequestBody User user, HttpServletRequest request){
    String token = request.getHeader("token");
    ResultController<User> result = new ResultController<>();
    result.setState(0);
    result.setMsg("success"+token);
    result.setData(user);
    return result;
}

11. 文件上传测试

@RequestMapping(value = "test06",method = RequestMethod.POST)
@ApiOperation(value = "文件上传测试")
@ApiImplicitParams(
    {
   @ApiImplicitParam(paramType = "query",name = "userName",value = "用户名",required = 	     true,dataType = "String"),
   @ApiImplicitParam(paramType = "query",name = "id",value = "用户名id",required = true,dataType = "Integer")
    }
    )
    public ResultController<String> test06( @RequestParam("userName")String userName,
                                            @RequestParam("id")int id, MultipartFile file){
        ResultController<String> result = new ResultController();
        try {
            file.transferTo(new File("F:/nihaoma.jpg"));
            result.setData("我是小王子"+userName+"----"+id);
            result.setMsg("请求成功");
            result.setState(0);
        } catch (IOException e) {
            result.setData("我是小王子"+userName+"----"+id);
            result.setMsg("shibai");
            result.setState(1);
        }
        return result;
    }

12. 常见的注解

@Api:这个注解的主要功能是描述当前的Controller用来干嘛的
@ApiOperation: 这个注解的作用是说明当前接口的作用
@ApiImplicitParam:参数的说明
@ApiImplicitParams:多个参数的说明
@ApiParam:参数的说明(功能一般)
@ApiModel: 标注在实体类上，对接口中传输的对象的说明
@ApiModelProperty:对实体类中成员变量的说明，标注在成员变量上
@ApiResponse:返回结果的说明