SpringBoot集成Swagger(七)@ApiModel()注解一通百通 | Java随笔记

5,363 阅读3分钟

「这是我参与11月更文挑战的第23天,活动详情查看:2021最后一次更文挑战


相关文章

Java随笔记:Java随笔记


前言

  • 俗话说,磨刀不误砍柴工,前面的内容主要是对Swagger进行配置。
  • 今天要讲解的内容才是Swagger实际使用的实体配置,还有接口的配置。
  • 毕竟我们一直强调的是前后端联调,那么怎么样让前端一眼就看得懂我们的接口呢?

一、实体配置

1.1、实体配置案例

  • 首先建立学生实体类StudentResponse

    • @Data
      @ApiModel(value = "学生类")
      public class StudentResponse {
      ​
          @ApiModelProperty(value = "姓名")
          private String name;
          @ApiModelProperty(value = "年龄")
          private int age;
          @ApiModelProperty(value = "爱好")
          private String like;
      }
      
  • Controller修改返回值为StudentResponse

    • @RestController
      public class SwaggerTestController {
      ​
          @RequestMapping(value = "test-swagger",method = RequestMethod.GET)
          public StudentResponse dyTest(){
              return new StudentResponse();
          }
      ​
      }
      
  • 重启测试点击model查看

    • image-20211125222641389.png
  • 这样的话,前端对我们的返回值每个的说明都清清朗朗的!

  • 麻麻再也不用担心前端看不懂返回参数啦~

1.2、@ApiModel()注解

  • 既然知道有这么个注解可以对我们的返回值提供说明文档,那么这个注解究竟是什么?可以设置哪些参数呢?别急,下面我们慢慢道来。

  • 老规矩,点进去看看,这个注解有哪些参数?分别设置下看看有什么效果

    • @Target({ElementType.TYPE})
      @Retention(RetentionPolicy.RUNTIME)
      @Inherited
      public @interface ApiModel {
          String value() default "";
      ​
          String description() default "";
      ​
          Class<?> parent() default Void.class;
      ​
          String discriminator() default "";
      ​
          Class<?>[] subTypes() default {};
      ​
          String reference() default "";
      }
      
    • 解释说明:

  • 多参数设置:

    • 新建课程类CourseResponse
    • @ApiModel(value = "课程类")
      @Data
      public class CourseResponse {
      ​
          @ApiModelProperty(value = "课程")
          private String course;
      }
      
    • @Data
      @ApiModel(value = "学生类",description = "这是类的详细描述信息呀",parent = CourseResponse.class,subTypes = CourseResponse.class)
      public class StudentResponse{
      ​
          @ApiModelProperty(value = "姓名")
          private String name;
          @ApiModelProperty(value = "年龄")
          private int age;
          @ApiModelProperty(value = "爱好")
          private String like;
      ​
          @ApiModelProperty()
          private CourseResponse perResponse;
      }
      ​
      
  • 再次重启看看效果:

    • image-20211125225242897.png
  • 总结如下:

    • value属性:这个属性,提供的是类的一个备用名。如果我们不设置,那么默认情况下,将使用的是class类的名字。
    • description属性:对于类,提供一个详细的描述信息
    • parent属性:这个属性,描述的是类的一些父类的信息。
    • discriminator属性:这个属性解释起来有些麻烦,因为这个类主要是体现出了断言当中。
    • subTypes属性:举个实例,如果我们此时有一个父类Animal。同时,对于这个父类,我们的系统中有这个类的子类CatDogPig等。如果我们在我们的父类上,通过这个属性,指定了我们想要使用的子类的话,那么在生成Swagger的文档的话,会自动的展示的是Animal这个属性,但是在属性的字段中,会显示出子类的一些独有的属性,其实在这里,是不推荐使用的。因为这样会让别人认为,这些子类独有的属性,也是父类才有的。
  • 关于discriminator这个属性,容我后面单独出个断言文章再来填坑。。因为我现在也不大会。。
  • 十一点了哇靠!明日再战!
  • 明日预告:@ApiModelProperty()详解。

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

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