Swagger 常用注解使用详解

环境：

1.这里使用的版本：springfox-swagger2（2.6.9）springfox-swagger-ui （2.9.2）
2.这里是说明常用注解的含义和基本用法（也就是说已经对swagger进行集成完成）

一、注解概述:

常用注解：

• @Api()用于类；
  表示标识这个类是swagger的资源 ，@Api 注解用于标注一个Controller（Class）
• @ApiOperation()用于方法；
  表示一个http请求的操作
• @ApiParam()用于方法，参数，字段说明；
  表示对参数的添加元数据（说明或是否必填等）
• @ApiModel()用于类
  表示对类进行说明，用于参数用实体类接收
• @ApiModelProperty()用于方法，字段
  表示对model属性的说明或者数据操作更改
• @ApiIgnore()用于类，方法，方法参数
  表示这个方法或者类被忽略
• @ApiImplicitParam() 用于方法
  表示单独的请求参数
• @ApiImplicitParams() 用于方法，包含多个 @ApiImplicitParam

二、注解使用：

1.@Api

@Api 注解用于标注一个Controller==（Class）。在默认情况下，Swagger-Core只会扫描解析具有@Api注解的类，而会自动忽略其他类别资源（JAX-RS endpoints，Servlets等等）的注解。

@Api属性一览表：

示例代码：

@Controller
@Slf4j
@RequestMapping("/user")
@Api(tags = "人员信息 API", description = "提供人员信息相关的 Rest API",value="controller类")
public class UserController extends BaseController {
 
}

2.@ApiOperation

@ApiOperation 注解在用于对一个操作或HTTP方法进行描述（用于@mapping方法上）==。具有相同路径的不同操作会被归组为同一个操作对象。不同的HTTP请求方法及路径组合构成一个唯一操作。

示例代码：

	@ApiOperation("根据id查询")
    @GetMapping("/getById/{id}")
    public Stutest getById(@ApiParam(name = "id",required = true) 
                               @PathVariable("id") Long id){
        Stutest byId = stutestService.getById(id);
        return byId;
    }

3.@ApiParam

@ApiParam作用于请求方法上，定义api参数的注解。

示例代码：
name： 参数名
value： 参数说明
required：是否必填

public ResponseEntity<User> getUserById(
            @ApiParam(name="id",value = "ID of user that needs to be fetched",
                    allowableValues = "range[1,10]", required = true)
            @PathVariable("UserId") Long userId)

4.@ApiImplicitParams、@ApiImplicitParam

@ApiImplicitParams、@ApiImplicitParam 都可以定义参数.

(1).@ApiImplicitParam() 用于方法
表示单独的请求参数

(2).@ApiImplicitParams() 用于方法，包含多个 @ApiImplicitParam ，用在请求的方法上，包含一组参数说明；

name–参数名字
value–参数说明
dataType–数据类型
paramType–参数类型
example–举例说明

代码示例：

/**
 * <pre>
 *  登录API接口
 * </pre>
 *
 * @since 2022-06-10
 */
@ApiImplicitParams({
        //参数效验
		@ApiImplicitParam(name="phonenum",value="手机号",required=true,paramType="form"),
		@ApiImplicitParam(name="password",value="密码",required=true,paramType="form"),
		@ApiImplicitParam(name="age",value="年龄",required=true,paramType="form",dataType="Integer")
	})
	@PostMapping("/login")
	public ApiResult login(@RequestParam String mobile, @RequestParam String password,
	@RequestParam Integer age){
		//...
	    return JsonResult.ok(map);
	}

5.@ApiResponses、@ApiResponse

@ApiResponses、@ApiResponse进行方法返回对象的说明。

代码示例:

@ApiResponses({
		@ApiResponse(code = 200, message = "请求成功"),
		@ApiResponse(code = 400, message = "请求参数没填好"),
		@ApiResponse(code = 404, message = "请求路径没有或页面跳转路径不对")
	}) 
	@ResponseBody
	@RequestMapping("/user")
	public ApiResult getUser(@RequestParam String userId) {
		...
	}

6.@ApiModel、@ApiModelProperty

@ApiModel用于描述一个Model的信息（这种一般用在post创建的时候，使用@RequestBody这样的场景，请求参数无法使用@ApiImplicitParam注解进行描述的时候）。

@ApiModelProperty用来描述一个Model的属性

使用场景

@ApiModel 用在模型类上,对模型类作注解

@ApiModelProperty 用在属性上,对属性作注解

代码演示:

/**
 * <pre>
 *     人员信息类
 * </pre>
 *
 */
@Data
@ApiModel(description= "返回人员信息")
public class UserQueryVo extends BaseEntity{
 
    @ApiModelProperty(value = "主键", required = true)
    @TableId(value = "id", type = IdType.ID_WORKER)
    private Long id;
    
    @ApiModelProperty(value = "手机号", required = true)
    private String phonenum;
 
    @ApiModelProperty(value = "密码", required = true)
    private String password;
    
    @ApiModelProperty(value = "年龄", required = true)
    private Integer age;
}

7.@PathVariable

@PathVariable用于获取get请求url路径上的参数，即参数绑定的作用，通俗的说是url中"?"前面绑定的参数。

 /**
     * 人员信息
     */
    @GetMapping("/info/{id}")
    @RequiresPermissions("tour:vehicle:info:info")
    @ApiOperation(value = "获取user对象详情", notes = "查看人员信息")
    public ApiResult<UserQueryVo> getTourVehicleInfo(@PathVariable("id") Long id) throws Exception {
        UserQueryVo userQueryVo= userService.getTourVehicleInfoById(id);
        return ApiResult.ok(userQueryVo);
    }