大家好！我是渣哥，是一个每天都在攒钱植发的程序猿。
今天跟大家聊聊项目开发，尤其是前后端分离的项目开发中经常遇到的两个问题。
一个是接口调试
后端的接口写好之后，要用各种调试工具，如PostMan等，去做接口调试，说实话，渣哥是不太喜欢用PostMan的，啥都需要手输，输错了就会有各种问题。
一个是接口文档
如果这个项目只有你一个人开发还好说，如果涉及到前端跟后端的分工合作，你后端写好之后，还需要写一份后端的接口文档，用于告知前端的伙伴该如何调用你写的接口，传入什么参数，返回什么数据，如何解析等等；如果这些内容都需要手写的话，一方面我们会浪费大量的时间，另一方面也没有办法做到实时同步，可能你后端的接口已经改了，但是你的接口文档还是之前的版本，这样就会导致前端同学使用你的接口时，明明按照你的接口文档传入数据了，但是得不到想要的结果。这时候前端的投诉就来了，老板就会来找你谈话了，绩效就完不成了，升任CEO，迎娶白富美，走上人生巅峰的目标就破灭了。
这怎么可以！！！
你肯定在想：难道就没有一个偷懒的办法嘛？我想要更简单的接口调试 ，我不想要手动去编写接口文档啊喂！天哪！谁能来救救我啊！
别着急，渣哥来救你！你想要接口调试更简单？你想要自动生成接口文档？Swagger统统满足你！
渣哥，你说swagger那么牛批，到底是个啥啊？
Swagger是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法，参数和模型紧密集成到服务器端的代码，允许API来始终保持同步。
说点人话就是使用Swagger可以让你无须关注接口文档，专心的开发，至于文档，你只需要多写几个注解，Swagger就可以自动帮你生成，并且还有配套的UI界面，跟你编写的接口实时更新，确保同步；并且在界面里你还可以做到实时调试，连PostMan都不需要用了，后端接口调试从未如此轻松！
那么Swagger如此牛批，咱们要怎么使用Swagger呢？
如何使用Swagger
1、导入依赖
假定你现在已经搭建好了一个基础的SpringBoot项目，想要使用Swagger第一步当然是导入依赖了，导入的依赖有两个，一个是Swagger自己的依赖，一个是SwaggerUI的依赖，有了这个依赖 ，你才能看到Swagger的UI界面。//不要忘了SpringWeb的依赖，我就不演示了哈。
<!-- Swgger依赖-->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.9.2</version>
</dependency>
<!-- SwggerUI依赖-->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.9.2</version>
</dependency>
2、编写配置类
新建一个SwaggerConfig
的配置类。
@Configuration
@EnableSwagger2
public class SwaggerConfig {
@Bean
public Docket getDocket() {
//创建ApiInfo的构建对象，用于生成ApiInfo对象;
ApiInfoBuilder apiInfoBuilder = new ApiInfoBuilder()
//标题
.title("Swagger生成的后端接口文档")
//描述信息
.description("用于测试Swagger的使用")
// 版本
.version("1.0.0")
//作者信息
.contact(new Contact("作者", "个人主页", "邮箱"));
ApiInfo apiInfo = apiInfoBuilder.build();
//指定文档风格
return new Docket(DocumentationType.SWAGGER_2)
//指定生成的封面信息
.apiInfo(apiInfo)
//指定文档生成策略
.select()
//指定那些包生成API文档
.apis(RequestHandlerSelectors.basePackage("Controller包路径"))
//构建
.build();
}
}
通过上面简单的两步，我们就配置好了Swagger的基础使用，现在我们把项目启动起来，然后进入：http://localhost:8080/swagger-ui.html
就可以看到基础的Swagger-ui界面了。
我们现在已经看到了Swagger的页面了，但是里面一个接口都还没有，那怎么把我们写的接口显示在这里呢？这里就需要用到Swagger的注解了。
● @Api(tags = "")
该注解打在Controller的类名上，可以定义该Controller要显示的名称。
@Api(tags = "测试接口组")
public class TestController {
...
}
● @ApiOperation("接口说明")
该注解打在Controller的方法上，用于说明该接口是干嘛的。
@GetMapping("test")
@ResponseBody
@ApiOperation("这是该接口的说明")
public String test1(String name, String password) {
return name + password;
}
●@ApiIgnore：
如果在某一方法上使用了这个注解之后，这个接口将不会在Swagger里显示
●@ApiImplicitParams：
定义方法的收参信息集合 ，内含一个或多个@ApiImplicitParam
●@ApiImplicitParam(name="参数名",value="参数描述")
定义具体的参数信息：
@ApiImplicitParams({
@ApiImplicitParam(name = "name", value = "用户名"),
@ApiImplicitParam(name = "password", value = "密码")
})
●@ApiModel("")
描述一个Model的信息。
●@ApiModelProperty("")
：描述一个model的属性。
@ApiModel("返回的结果集对象")
public class ResultVO {
@ApiModelProperty("返回码")
private Integer code;
@ApiModelProperty("返回消息")
private String msg;
@ApiModelProperty("返回数据")
private Object data;
}
看到这里，我想你已经基本了解了Swagger了，但是现在看到的页面都还是纯英文的，对于外语不好的小伙伴有点不友好（比如渣哥本人），并且调试起来，也不太直观；要是有更好看的UI，最好是纯中文的，调试也比较方便那就更好了，哈哈哈，巧了，有！
BootStrapUI
咱们刚刚导入的Swagger-UI是Swagger官方的UI，界面不好看，并且基本都是纯英文界面，渣哥不喜欢，那我们就把它换掉！接下来我们使用另一个UI，这个UI是BootStrap提供的，我们来试试吧！
第一步：换UI，把之前原生的UI依赖改成这个。
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>swagger-bootstrap-ui</artifactId>
<version>1.9.6</version>
</dependency>
第二步：重启项目，换掉UI之后，它的默认的访问地址也是需要改一下的，现在我们去访问：http://localhost:8080/doc.html
看，这样的界面是不是更友好呢？
调试起来也更为友好，不需要我们再去输入路径、请求方式、参数名等等。
好了，今天关于Swagger的学习就到这里，大家看完之后一定要自己去敲一敲，要把今天学到的知识变成熟练使用Swagger的能力哦！我是渣哥，咱们下期见！
