Swagger比较常用的注解 - OXOXTECH 牛牛技术客栈

军阁 2024-01-05 17:23:05 后端 Swagger

一、@Api

多作用在Controller类上，用来描述类信息

参数：
1.description：描述这个类的作用。
2.tags：设置这个类的一个标签。

@Api(tags = "招聘管理",description = "用于招聘模块的测试")
@Controller
public class ResumeController {
 
}

二、@ApiOperation

作用在Controller类的方法上，用来描述接口信息

参数：value可以加以说明

@ApiOperation(value = "简历的查询")
@RequestMapping(value="findResumeByID",method = RequestMethod.GET)
@ResponseBody
public DataResult findResume(String resumeID){
        
}

三、@ApilmplicitParam

作用在Controller类的方法上，用来描述接口的参数信息(单参)

参数：
1.name ：参数名。（注意这个名字要与实际方法中的参数名一致，不然会导致swagger界面出现多个参数）
2.value ：参数的具体意义，作用。（与方法上的参数名对应）
3.required ：参数是否必填。
4.dataType ：参数的数据类型。
5.paramType ：查询参数类型，这里有几种形式：
path 以地址的形式提交数据；
query 直接跟参数完成自动映射赋值；
body 以流的形式提交仅支持POST；
header 参数在request headers 里边提交；
form 以form表单的形式提交仅支持POST；）

@ApiImplicitParam(value = "根据简历id查询唯一的一份简历", name = "resumeID", paramType = "query", dataType = "String")
@RequestMapping(value="findResumeByID",method = RequestMethod.GET)
@ResponseBody
public DataResult findResume(String resumeID){
       
}

四、@ApilmplicitParams

作用在Controller类的方法上，用来描述接口的参数信息(多参)

在注解里面在包含多个@ApiImplicitParam注解，每个注解使用逗号隔开

@ResponseBody
@RequestMapping(value="findResumeByCand",method = RequestMethod.POST)
@ApiOperation(value = "多条件查询")
@ApiImplicitParams({
    @ApiImplicitParam(value="姓名",name="name",dataType="String",paramType = "query"),
    @ApiImplicitParam(value="简历状态",name="status",dataType="String",paramType = "query"),
    @ApiImplicitParam(value="简历来源",name="source",dataType="String",paramType = "query"),
    @ApiImplicitParam(value="开始时间",name="startTime",dataType="String",paramType = "query"),
    @ApiImplicitParam(value="结束时间",name="endTime",dataType="String",paramType = "query")
})
public DataResult findResumeByCand(String name,String status,String source,String startTime,String endTime){
   
}

五、@ApiParam

作用在方法的参数上，用来描述接口的参数信息(一个参设置一个)

增加对参数的元信息说明

@RequestMapping(value="uploadFile",consumes = "multipart/*",headers = "content-type=multipart/form-data",method = RequestMethod.POST)
@ResponseBody
public DataResult uploadFile(@ApiParam(value = "上传文件",required = true) MultipartFile file, String resumeID,HttpServletRequest request)throws IOException{
}

六、@ApiModel和@ApiModelProperty

当参数是以一个java对象时

@ApiModel：作用在实体类上

@ApiModelProperty：作用在实体类的属性上

@ApiModel(value="AppInfo",description="App信息实体类")
pubilc class AppInfo{
    @ApiModelProperty("App的id")
    private Interger id;
    @ApiModelProperty("软件名称")
    private String softwareName;
 
}

参考： https://blog.csdn.net/weixin_47609997/article/details/119146729

推荐订阅源

牛牛技术客栈