springboot整合swagger2
记录swagger使用-version2.9
注解描述参考(版本可能不一致):
https://blog.csdn.net/Jack_EUSong/article/details/80349694
https://blog.csdn.net/u014231523/article/details/76522486
接口使用(接受实体类参数)
@Api(value = “当前类的描述”) //作用于类上
@ApiOperation(value = “当前方法名”,notes = “当前方法的描述”)
@ApiResponses(当前返回类中有code参数,描述code参数, response = void.class)
@Valid (spring mvc注解,做校验用,需配合参数中 BindingResult )
@PostMapping("/category_page_search")
@ApiOperation(value = "根据分类查询并分页",notes = "根据分类ID查询商品并分页")
@ApiResponses({
@ApiResponse(code = 500, message = "内部错误"),
@ApiResponse(code = 400, message = "参数错误"),
@ApiResponse(code = 204, message = "没有返回结果"),
@ApiResponse(code = 200, message = "成功", response = ApiResult.class)
})
@ApiImplicitParams({
@ApiImplicitParam(name = "cid",value = "分类ID",required = true,dataType = "int"),
@ApiImplicitParam(name = "page",value = "当前页",required = true,dataType = "int"),
@ApiImplicitParam(name = "limit",value = "每页最大数",required = true,dataType = "int"),
@ApiImplicitParam(name = "sort",value = "排序方式(asc,desc)",required = true,dataType = "String"),
@ApiImplicitParam(name = "sort_column",value = "排序字段",required = true,dataType = "String")
})
public ApiResult> selectPageByCategoryid(@RequestParam("cid") int cid,
@RequestParam("page") int page,
@RequestParam("limit")int limit,
@RequestParam("sort")String sort,
@RequestParam("sort_column") String sortColumn,
@ApiParam(value = "搜索条件key,value", name = "search", required = false,type = "map") @RequestBody(required = false) Map search){
return spuClient.selectPageByCategoryid(cid,page,limit,sort,sortColumn,search);
接收参数为file类型
@ApiOperation(value = "批量添加商品",notes = "根据EXCEL添加商品")
@ApiResponses({
@ApiResponse(code = 400, message = "数据错误"),
@ApiResponse(code = 200, message = "添加成功", response = ApiResult.class)
})
@PostMapping(consumes = MediaType.MULTIPART_FORM_DATA_VALUE)
public ApiResult insertSpuForExcel(@ApiParam(value = "上传的文件", required = true) @RequestPart(value = "file") MultipartFile multipartFile){
return spuImportForExcelClient.insertSpuForExcel(multipartFile);
}
接收单独的参数(参数上的注解不一致)
@ApiOperation(value = "分类查询",notes = "根据ID查询分类")
@ApiResponses({
@ApiResponse(code = 500, message = "服务器错误"),
@ApiResponse(code = 400, message = "客户端提交信息错误"),
@ApiResponse(code = 401, message = "认证登录失败"),
@ApiResponse(code = 200, message = "认证成功并返回认证信息", response = CategoryResult.class)
})
@ApiImplicitParam(name = "id",value = "商品分类id",required = true,dataType = "Integer")
@RequestMapping(value = "/category/{id}",method = RequestMethod.GET)
public CategoryResult findById(
@PathVariable("id")
@NotEmpty(message = "不能为空") Integer id){
logger.info("执行 store-api ==>> SysCategoryController ");
return categoryClient.findById(id);
};
因为在上面第一个方法中 使用注解描述了请求参数和返回参数,都是实体类,所以需要在请求和返回参数中都添加注解作为API文档参数描述(swagger界面Models选项中显示)
请求body
@ApiModel(value=“当前类的描述”)
@ApiModelProperty(notes=“描述”,example=“例子”)
@Data
@JsonNaming(PropertyNamingStrategy.SnakeCaseStrategy.class)
@ApiModel(value = "添加分类addCategroy", description = "对应方法:addCategroy()")
public class AddRequestBody {
@NotBlank(message = "分类名称错误")
@ApiModelProperty(notes = "分类名称",example = "当前分类名称")
private String cateName;
@NotNull(message = "分类等级错误")
@ApiModelProperty(notes = "分类等级", example = "1")
private Integer cateLevel;
@NotBlank(message = "上级分类错误")
@ApiModelProperty(notes = "父级名称",example = "挖掘机")
private String parName;
}
返回body
注解同上
@ApiModelProperty(example = “当前参数的参照例子”)
@Data
@ApiModel(value = "分类responseBody",description = "分类请求返回")
public class CategoryResult implements Serializable {
private static final long serialVersionUID = 1L;
/** 返回code */
@ApiModelProperty(required = true,value = "结果返回值",name = "code",example = "200")
private String code;
/** 返回消息 */
@ApiModelProperty(required = true,value = "结果返回信息",name = "msg",example = "添加成功")
private String msg;
/** 返回数据 */
@ApiModelProperty(required = true,value = "结果返回数据",name = "data")
private Object data;
}
因为返回body中调用了实体类,所以也需要在实体类中加上注解,如果不加注解,在swagger界面models中,会出现一个与当前调用的实体类的注解同名的参数
实体类
@JsonNaming(PropertyNamingStrategy.SnakeCaseStrategy.class) // 格式转换
@TableId(type = IdType.AUTO)// mybatis-plus中描述主键注解
@Data
@JsonNaming(PropertyNamingStrategy.SnakeCaseStrategy.class)
@ApiModel(value = "category实体类",description = "category实体类")
public class SysCategory {
private static final long serialVersionUID = 1L;
@NotEmpty(message = "id不能为空")
@TableId(type = IdType.AUTO)
@ApiModelProperty(name = "id",value = "用户ID,主键")
private Integer id;
@ApiModelProperty(name = "name",value = "当前分类名称")
@NotEmpty(message = "分类名称不能为空")
private String name;
@ApiModelProperty(name = "parName",value = "当前分类父类名称")
@NotEmpty(message = "父类不能为空")
private String parName;
@ApiModelProperty(name = "level",value = "当前分类所属等级")
@NotEmpty(message = "分类等级不能为空")
private Integer level;
}
注:
@ApiParam()
@ApiImplicitParam()
区别:
@ApiParam() 作用与参数上,描述参数
@ApiImplicitParam() 作用与方法上,描述参数
上面两个参数,如果同时使用,会覆盖
描述单个参数的时候可以使用上面两个注解,如果参数是一个实体类,就需要使用@requestbody注解来接收参数,然后配合上面的@apimodel 注解
----------------
@apimodel这个注解不能单独使用,使用这个注解的类,需要在使用@api类中调用才能生效,如果不调用,在swagger界面models中看不到这个类的文档
例:
@api
类名a{
方法a(@requestbody abc){
...
}
}
@apimodel
abc{
}