一、前言：

作为一个开发，写接口文档是最让人痛苦的一件事情了，因为必须注明出参和入参，一不小心偷个懒吧，前台就出问题了，或者更新不及时，前后端的相爱相杀的大戏就要上演了。swagger 的出现大大的解决了这个问题，但是有很大程度上并不是所有人都会用。结合自己的爬坑之旅来完整的介绍一下 swagger 的攻略。

二、先用几张图说一下我们可能遇到的问题：

2.1 入参完全没有参数说明

image.png

2.2 出参也没有任何的说明以及类型

image.png

三、简单集成：

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 效果截图：

image.png
image.png

这个就会出现我们最开始的时候的效果，但是这样给前端去弄，照样还是有问题，相当于是没有是一样的。所以下面我们介绍如何解决这个问题

四、解决入参参数说明的问题

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 效果截图：

瞬间前后端又能相爱了，有木有

image.png

五、解决出参没有注释，没有类型的问题

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 改造后的效果图：

世界从此和平，前端和后端又能愉快的一起玩耍

image.png

上述就是关于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
希望结识更多的乐于分享的伙伴一起前行