Swagger常用注解的介绍及使用（详细）

一、前言

上一篇介绍了SpringBoot集成Swagger的相关内容和使用，本篇内容会介绍开发中Swagger经常使用的注解，因为本篇是接着上一篇写的，所以如果你不知道如何使用SpringBoot集成Swagger，请移至SpringBoot集成Swagger快速开发

二、常用注解介绍及使用案例

 1、@ApiModel和@ApiModelProperty注解

  介绍
  @ApiModel注解是用在实体类上的注解，它主要是用来对相关的实体类添加额外的描述信息，并且常常和@ApiModelProperty注解配合使用。

  @ApiModelProperty注解是作用在实体类的属性上的注解，用来对具体实体类中的属性添加额外的描述信息。

  也就是说@ApiModel 和@ApiModelProperty两个注解的作用域不同，它们都是作用在接口相关的实体类上用来进行额外信息的描述，只是一个是作用在类上，一个作用在属性上。

 使用如下：

@ApiModel(description = "员工类")
// description属性作用是对所需要特别说明的实体类进行相关的描述。
public class Employee {
    @ApiModelProperty(value = "员工ID")
    // value属性就是对实体类中的字段进行描述和补充说明，解释该字段代表什么意思。
    private Long id;

    @ApiModelProperty(value = "用户名")
    private String username;

    @ApiModelProperty(value = "姓名")
    private String name;

    @ApiModelProperty(value = "密码")
    private String password;

    @ApiModelProperty(value = "电话号码")
    private String phone;

    @ApiModelProperty(value = "性别")
    private String sex;
    }

💡 使用注解前后界面对比

可以发现多了相关描述内容，这样我们后期的相关操作就会更加高效

2、@Api和@ApiOperation注解

  介绍
  @Api注解是用在类上的注解，它主要是用来对相关的类添加额外的描述信息

  @ApiOperation使用于在方法上，表示一个http请求的操作

 使用如下：

@Api(tags = "员工管理")
@RestController
public class EmployeeController {
	@ApiOperation("添加员工功能")
    @PostMapping("/save")
    public Result<String> saveEmployee(@RequestBody Employee employee) {
        ......
    }
}

💡 使用注解前后界面对比

3、@ApiParam注解

  介绍
  @ApiParam注解使用在方法上或者参数上，该注解的属性说明如下：

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

 使用如下：

@Api(tags = "员工管理")
@RestController
public class EmployeeController {
	@ApiOperation("根据id查询员工")
	@GetMapping("/{id}")
    public Result<Employee> queryEmployeeById(@ApiParam(name = "id", value = "员工id", required = true) 
                                             @PathVariable Long id) {
        ......

    }
}

💡 使用注解前后界面对比

如果本篇文章对你有帮助的话，请点个赞叭~