美文网首页Java 杂谈
你不知道的swagger技巧,顺带介绍一下lombok的坑

你不知道的swagger技巧,顺带介绍一下lombok的坑

作者: fkxuexi | 来源:发表于2019-02-19 10:26 被阅读2次

    一、前言:

    作为一个开发,写接口文档是最让人痛苦的一件事情了,因为必须注明出参和入参,一不小心偷个懒吧,前台就出问题了,或者更新不及时,前后端的相爱相杀的大戏就要上演了。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
    希望结识更多的乐于分享的伙伴一起前行

    相关文章

      网友评论

        本文标题:你不知道的swagger技巧,顺带介绍一下lombok的坑

        本文链接:https://www.haomeiwen.com/subject/nvtxyqtx.html