526互联

Swagger核心注解总结

发布时间 2023-08-28 10:34:30作者: 角刀牛Java

      • 文章目录

        一、前言

        本文介绍了swagger的一些注解应用，有swagger2版本的和swagger3.0版本的注解，基本上差不多，在这里我只介绍了一些常用的注解和注解的一些参数等，想要了解更多可以去百度查找。

        二、Swagger接口文档注解image

        1、@Api

        作用： 使用在类上，表明是swagger资源，@Api拥有两个属性:value、tags。controller中的所有接口生成的接口文档都会在tags这个list下；tags如果有多个值，会生成多个list，每个list都显示所有接口。

        应用代码：

        @Api(value="图书接口",tags = "图书管理")
@RestController
@RequestMapping(value = "/book")
public class BookController {
}

        如下图所示：image

        2、@ApiOperation

        作用： 用于在方法上，表示一个http请求的操作，用在项目的接口类的方法上。value用于方法描述，notes用于提示内容。

        应用代码：

        @ApiOperation(value = "获取所有的书", notes = "")
@PostMapping(value = "/list")
public Result booklist(){
    // 内容
}

        image

        3、@EnableOpenApi

        作用： 在用到swagger3.0版本的时候就可以用到这个注解了，可以放在启动类上或者是swagger的配置文件上。

        应用代码：

        @Configuration
@EnableOpenApi
public class Swagger2Configuration {
    //放一些swagger的配置信息，添加项目接口版本号，指定controller类等。
}

        4、@ApiImplicitParam

        作用： 用在@ApiImplicitParams注解中，指定一个请求参数的各个方面

        • name：参数名
        • value：参数的汉字说明、解释
          required：参数是否必须传
        • paramType：参数放在哪个地方

        应用代码：

          @ApiOperation(value = "获取所有的书", notes = "")
  @PostMapping(value = "/list")
  @ApiImplicitParams({@ApiImplicitParam(name = "book", value = "所有的书", paramType = "Long")})
  public Result booklist(){
       
  }

        5、@ApiImplicitParams

        作用： 用在请求的方法上，表示一组参数说明，和@ApiImplicitParam配合使用。

        应用代码：

          @ApiOperation(value = "获取所有的书", notes = "")
  @PostMapping(value = "/list")
  @ApiImplicitParams({@ApiImplicitParam(name = "book", value = "所有的书", paramType = "Long")})
  public Result booklist(){
       
  }

        6、@ApiParam

        作用： 使用在方法上或者参数上，字段说明；表示对参数的添加元数据（说明或是否必填等）。(目前不常用)

        • name–参数名
        • value–参数说明
        • required–是否必填

        应用代码：

        public class BookController {
     @ApiOperation(value="获取所有的书",tags={"获取所有的书copy"},notes="注意问题")
     @PostMapping(value = "/list")
     public Result getUserInfo(@ApiParam(name="id",value="用户id",required=true) Long id,@ApiParam(name="username",value="用户名") String username) {
      //可忽略业务逻辑
      List<Book> all = bookService.findAll();
      return new Result().success(200, all);
  }
}

        7、@EnableSwagger2

        作用： 在用到swagger2.0版本的时候就可以用到这个注解了，可以放在启动类上或者是swagger的配置文件上。

        应用代码：

        @Configuration
@EnableSwagger2
public class Swagger2Configuration {
    //放一些swagger的配置信息，添加项目接口版本号，指定controller类等。
}

        暂时就整理以上七个注解