Swagger核心注解总结（四）

拼搏现实的明天。 2022-09-10 11:11 218阅读 0赞

### 文章目录 ###

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

## 一、前言 ##

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

## 二、Swagger接口文档注解 ##

![在这里插入图片描述][watermark_type_ZHJvaWRzYW5zZmFsbGJhY2s_shadow_50_text_Q1NETiBA56CB5LiK6KiA_size_20_color_FFFFFF_t_70_g_se_x_16]

### 1、@Api ###

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

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

如下图所示：  
![在这里插入图片描述][d1cf6e7897b24776aec3beec66503ed3.png]

### 2、@ApiOperation ###

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

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

![022b70b2eb16f6a4b82c10a36fd4747e.png][]

### 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`配合使用。

**应用代码：**

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

暂时就整理以上七个注解吧，以后遇到其它的我再更新，整理累死个人，别忘了点赞、收藏、关注哦!  
![在这里插入图片描述][watermark_type_ZHJvaWRzYW5zZmFsbGJhY2s_shadow_50_text_Q1NETiBA56CB5LiK6KiA_size_17_color_FFFFFF_t_70_g_se_x_16]

上一篇：[Mybatis核心注解总结（三）][Mybatis]

有什么问题欢迎私信和我交流。或者关注我的微信公众号`码上言`获得更多的学习。

![微信公众号：码上言][26e793d93499cb2c2afa75ea987e42a3.png]

[watermark_type_ZHJvaWRzYW5zZmFsbGJhY2s_shadow_50_text_Q1NETiBA56CB5LiK6KiA_size_20_color_FFFFFF_t_70_g_se_x_16]: /images/20220829/55b929373a0e449ebf4b52ef57904c4d.png
[d1cf6e7897b24776aec3beec66503ed3.png]: /images/20220829/9fe981efe1bf4203a8de956b531b2ffe.png
[022b70b2eb16f6a4b82c10a36fd4747e.png]: /images/20220829/cbc1dd9302974e919f1e28759397ed03.png
[watermark_type_ZHJvaWRzYW5zZmFsbGJhY2s_shadow_50_text_Q1NETiBA56CB5LiK6KiA_size_17_color_FFFFFF_t_70_g_se_x_16]: /images/20220829/ff31f2925a514bbabf10a1702f904466.png
[Mybatis]: https://blog.csdn.net/m0_37779600/article/details/120187662
[26e793d93499cb2c2afa75ea987e42a3.png]: /images/20220829/ca200690f0eb470f9550bf065af39752.png