Swagger核心注解总结

• 文章目录

  • 一、前言
  • 二、Swagger接口文档注解
  • 1、@Api
  • 2、@ApiOperation
  • 3、@EnableOpenApi
  • 4、@ApiImplicitParam
  • 5、@ApiImplicitParams
  • 6、@ApiParam
  • 7、@EnableSwagger2

  一、前言

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

  二、Swagger接口文档注解

  

   

   

  1、@Api

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

  应用代码：

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

  如下图所示：
  

  2、@ApiOperation

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

  应用代码：

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

  
  

  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类等。
  }
  

  暂时就整理以上七个注解