一、前言：
作为一个开发，写接口文档是最让人痛苦的一件事情了，因为必须注明出参和入参，一不小心偷个懒吧，前台就出问题了，或者更新不及时，前后端的相爱相杀的大戏就要上演了。swagger 的出现大大的解决了这个问题，但是有很大程度上并不是所有人都会用。结合自己的爬坑之旅来完整的介绍一下 swagger 的攻略。
二、先用几张图说一下我们可能遇到的问题：
2.1 入参完全没有参数说明
2.2 出参也没有任何的说明以及类型
三、简单集成：
3.1 环境：
- springboot 2.1.0.RELEASE
- swagger
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.8.0</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.8.0</version>
</dependency>
3.2 简单配置：
@EnableSwagger2
@Configuration
public class SwaggerConfig {
//swagger2的配置文件，这里可以配置swagger2的一些基本的内容，比如扫描的包等等
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
//为当前包路径
.apis(RequestHandlerSelectors.basePackage("com.yuebao.goldbang.controller"))
.paths(PathSelectors.any())
.build();
}
//构建 api文档的详细信息函数,注意这里的注解引用的是哪个
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
//页面标题
.title("粤宝黄金邦 API ")
//创建人
//.contact(new Contact("MarryFeng", "http://www.baidu.com", ""))
//版本号
.version("1.0")
//描述
.description("this api for yuebao goldbangs ")
.build();
}
}
3.3 简单使用
@RestController
@Api(description = "this controller just for test some new feature or debug")
@RequestMapping("/api/test/")
public class TestFeatureController {
@ApiOperation("测试一下 swagger 功能")
@PostMapping("testSwagger")
public ResResult testSwagger(SwaggerTest swaggerTest){
swaggerTest.setAddr("湖北");
swaggerTest.setAge(18);
swaggerTest.setName("blog.fkxuexi.top");
return ResResult.builder().data(swaggerTest).code(ResCode.SUCCESS).status(true).build();
}
}
3.4 ResResult 实体
这里是使用了lombok
@ToString
@Builder
public class ResResult<T> {
@Setter@Getter private Integer code;
@Setter@Getter private boolean status;
@Setter@Getter private T data;
@Setter@Getter private String msg;
}
3.5 效果截图：
这个就会出现我们最开始的时候的效果，但是这样给前端去弄，照样还是有问题，相当于是没有是一样的。所以下面我们介绍如何解决这个问题
四、解决入参参数说明的问题
4.1、使用下列注解完成
- @ApiModel 注明这个类需要文档注释，但是就这一个还不够
- @ApiModelProperty(“用户id”) 具体的注释参数的含义
@ToString
@Getter
@Setter
@ApiModel
public class SwaggerTest {
@ApiModelProperty("用户id")
private Integer id;
@ApiModelProperty("用户姓名，必须是英文（这只是个比方）")
private String name;
@ApiModelProperty("用户地址")
private String addr;
@ApiModelProperty("用户年龄")
private Integer age;
}
4.2 效果截图：
瞬间前后端又能相爱了，有木有
五、解决出参没有注释，没有类型的问题
5.1 公共返回实体需要注意的地方
公共实体的返回的数据类型需要是泛型的
5.2 controller 请求方法返回值的改造
@ApiOperation("测试一下 swagger 功能")
@PostMapping("testSwagger")
public ResResult<SwaggerTest> testSwagger(SwaggerTest swaggerTest){
swaggerTest.setAddr("湖北");
swaggerTest.setAge(18);
swaggerTest.setName("blog.fkxuexi.top");
return ResResult.<SwaggerTest>builder().data(swaggerTest).code(ResCode.SUCCESS).status(true).build();
}
5.3 改造后的效果图：
世界从此和平，前端和后端又能愉快的一起玩耍
上述就是关于swagger 的一些使用技巧，当然一些常用的注解这里没有讲到，这个随便的百度一下就可以找到，就不在多余的赘述了。
六、lombok的简介以及一些坑
6.1 讲解一下 lombok的好处吧：
lombok 不同于其他的注解，它是在编译期间动态的修改源码，其实可以达到反射一样的效果，但是它比反射更加的高效，是在编译器执行的。
6.2 在使用的时候请避开下列的坑：
具体的我就不再举例，因为好多我也忘了，但是我记得最好是不用这些注解
6.2.1 慎用构造器注解
因为构造器注解是不支持重载的，以及很多时候结合mybatis用会出现问题
6.2.2 慎用builder 注解
builder的模式的使用在结合mybatis的时候很多情况下也会出现问题
6.2.3 选用builder注解：
很多时候我们会创建公共的响应类，但是很多时候我们会把data的类型和msg的类型都设置为Object，此时构造方法难以区分这两个参数，所以这个时候使用builder 注解是最好的。
博客首发地址csdn：https://blog.csdn.net/weixin_42849915
简书地址：https://www.jianshu.com/u/4b48be4cf59f
希望结识更多的乐于分享的伙伴一起前行