SpringBoot集成Swagger（十一）常用注解介绍

发表于

「这是我参与11月更文挑战的第28天，活动详情查看：2021最后一次更文挑战」

相关文章

Java随笔记：Java随笔记

前言

  • 上篇文章没有介绍完所有的常用注解，今天来补充最后四个常用注解。
  • 还有一些其他的注解，感兴趣的小伙伴们可以自行研究了，在此笔者不在赘述了。
  • 平时我们在开发过程中，可以酌情使用。
  • 希望对你们有所帮助。
  • 不要嫌弃我水着分开发，为了更文活动，不寒碜！你懂得！

一、ApiResponse

  • @ApiResponse 用于方法上，说明接口响应的一些信息。

  • 1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    less复制代码@RestController
    @Api(tags = "Swagger测试类")
    public class SwaggerTestController {
        @ApiResponse(code = 200,message = "success", response = StudentResponse.class)
        @RequestMapping(value = "test-swagger",method = RequestMethod.GET)
        @ApiOperation(value = "查询学生详情",notes = "参数为id")
        public StudentResponse dyTest(){
            return new StudentResponse();
        }
    }

  • 效果如下：

  • image-20211129221220096.png

二、ApiResponses

  • 上面的只定义了200的状态码，如果是500呢？

  • @ApiResponses就是多个@ApiResponse组装起来。

  • 1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    less复制代码@RestController
    @Api(tags = "Swagger测试类")
    public class SwaggerTestController {
    //    @ApiResponse(code = 200,message = "success", response = StudentResponse.class)
        @ApiResponses({@ApiResponse(code = 200,message = "success", response = StudentResponse.class),
                @ApiResponse(code = 500,message = "failed", response = StudentResponse.class)})
        @RequestMapping(value = "test-swagger",method = RequestMethod.GET)
        @ApiOperation(value = "查询学生详情",notes = "参数为id")
        public StudentResponse dyTest(){
            return new StudentResponse();
        }
    }

  • 效果如下：

  • image-20211129221454085.png

三、ApiImplicitParam

  • 如果我们的参数较少的时候，比如，根据id查询指定数据详细信息的时候，我们总不能单独建个实体来描述吧？
  • 通常我们的做法时，五个参数以下时，可以通过ApiImplicitParam来对参数进行描述。
  • 当然，只限于Get请求，如果是添加、修改等操作，Post、Put请求时还是以实体类为主！

  • @ApiImplicitParam用于方法上，为单独的请求参数进行说明。

  • 1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    less复制代码@RestController
    @Api(tags = "Swagger测试类")
    public class SwaggerTestController {
        @ApiResponses({@ApiResponse(code = 200,message = "success", response = StudentResponse.class),
                @ApiResponse(code = 500,message = "failed", response = StudentResponse.class)})
        @RequestMapping(value = "test-swagger",method = RequestMethod.GET)
        @ApiOperation(value = "查询学生详情",notes = "参数为id")
        @ApiImplicitParam(name = "id", value = "学生ID", dataType = "string", paramType = "query", required = true, defaultValue = "1")
        public StudentResponse dyTest(String id){
            return new StudentResponse();
        }
    }

  • 效果如下：

  • image-20211129222607574.png

四、ApiImplicitParams

  • 多个参数时，ApiImplicitParam可能就满足不了我们的要求了，这时候需要组装下！

  • 同样的，多个@ApiImplicitParam组装起来。

  • 1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    less复制代码@RestController
    @Api(tags = "Swagger测试类")
    public class SwaggerTestController {
        @ApiResponses({@ApiResponse(code = 200,message = "success", response = StudentResponse.class),
                @ApiResponse(code = 500,message = "failed", response = StudentResponse.class)})
        @RequestMapping(value = "test-swagger",method = RequestMethod.GET)
        @ApiOperation(value = "查询学生详情",notes = "参数为id")
    //    @ApiImplicitParam(name = "id", value = "学生ID", dataType = "string", paramType = "query", required = true, defaultValue = "1")
        @ApiImplicitParams({@ApiImplicitParam(name = "id", value = "学生ID", dataType = "string", paramType = "query", required = true, defaultValue = "1"),
                @ApiImplicitParam(name = "name", value = "学生姓名", dataType = "string", paramType = "query", required = true, defaultValue = "1")})
        public StudentResponse dyTest(String id){
            return new StudentResponse();
        }
    }
    ​

  • 效果如下：

  • image-20211129222839545.png

总结

  • 到这里Swagger系列是真的结束了。再也没有东西可讲了。
  • 看完本系列的所有文章，相信你对Swagger有了相对来说比较深得了解了。
  • 希望对你有所帮助，本系列不说是全网最详细也差不多啦吧！
  • 哈哈哈，我可以整理了很多的才最终整合出来的！
  • 本系列文章都是个人见解，如有不对，敬请指出~
  • 轻喷！谢谢~

路漫漫其修远兮，吾必将上下求索~

如果你认为i博主写的不错！写作不易，请点赞、关注、评论给博主一个鼓励吧~hahah

本文转载自: 掘金

开发者博客 – 和开发相关的 这里全都有

0%