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

暂时就整理以上七个注解吧，以后遇到其它的我再更新，整理累死个人，别忘了点赞、关注哦!

​

微信公众号​​码上言​​获得更多的学习。