目录
4、 @ApiImplicitParams和@ApiImplicitParam
一、导语
在现代的Web开发中,API注释在对接接口过程中变得越来越重要。开发者们需要能够相互了解API的设计和实现方式,以便协同工作。作为一种流行的API文档技术,Swagger2提供了强大的注释能力,它使开发者们能够详尽地记录和描述API的细节和要求,从而更容易地理解和使用API。在这篇博客中,我们将探讨Swagger2的API注释技术,并演示如何使用它与前端开发人员更好地对接接口。我们将介绍如何使用Swagger2的注释功能,如何为API添加参数和返回值注释,以及如何为API添加标签和示例代码。在阅读本文后,您将学会如何使用Swagger2的注释功能来使API的文档更加明确和易于理解,从而更轻松地与前端开发人员对接接口。
二、注释及用法
1、@Api
格式:
@Api(value = "xx接口",tags = "xx接口")
用在controller类的类开头,解释这个类是一个什么接口,指定API的名称、描述和版本等基本信息。
例如:
2、 @ApiOperation
格式:
@ApiOperation(value = "xxx",notes ="xxx")
用于描述API操作的基本信息,包括操作名称、描述和HTTP请求方法等。@ApiOperation注释通常需要添加在API方法上,它的常用属性包括value、notes、response、responseContainer、responseHeaders、tags等,其中value和notes是最为重要的属性。(其他属性为可选,这两个为必选)
value属性:它指定了API操作方法的名称。
notes属性:用于解释API的一些具体细节。例如:“接口需要传递的参数格式、参数类型,参数范围等描述”,“接口返回值类型、是否可以为空、是否多选等详细信息描述”等。notes属性的使用通常可以减少API的误解和错误调用。
例如:
3、@ApiParam
常用于单参数或者参数较少的情况,用于描述API接口中的参数信息。它通常需要添加在API方法的具体参数上,它的常用属性包括name、value、defaultValue、required、allowableValues、access、allowMultiple等。
常用的@ApiParam属性:
- name:参数名称,用于显示参数,必填项。
- value:参数的简洁描述,可选项。
- defaultValue:参数的默认值,可选项。
- required:参数是否是必填项,默认为false。
- allowableValues:参数的可选值,用于枚举类型参数定义,例如限制字符串变量的取值范围。
- access:参数的访问权限,可选的值有PRIVATE、PUBLIC和UNDEFINED,分别表示私有、公开和未定义。默认值为:“PUBLIC”。
- allowMultiple:是否允许多个值,针对数组类型参数。默认为false。
格式:
@ApiParam(value = "xxx", required = true, example = "1")
例如:
4、 @ApiImplicitParams和@ApiImplicitParam
用于多参数的情况。@ApiImplicitParams包含@ApiImplicitParam,通过添加多个@ApiImplicitParam注释,用于描述API接口的请求参数列表,包括参数名称、描述、是否必需、参数类型等信息。
- name:参数名称,用于显示参数,必填项。
- value:参数的简洁描述,可选项。
- required:参数是否是必填项,默认为false。
- dataType:参数类型,必填项。
- paramType:参数位置,可选的有Query、Header、Path、Body、Form-data等。最常用的为path和query,path常用于单参数且该参数是必须的情况下,query常用于多参数,参数可为可选的情况下。
例如:
@ApiOperation(value = "添加用户", notes = "根据User对象创建用户")
@ApiImplicitParams({
@ApiImplicitParam(name = "username", value = "用户名称", required = true, dataType = "String", paramType = "query"),
@ApiImplicitParam(name = "password", value = "用户密码", required = true, dataType = "String", paramType = "query"),
@ApiImplicitParam(name = "age", value = "用户年龄", required = false, dataType = "int", paramType = "query"),
@ApiImplicitParam(name = "email", value = "用户邮箱", required = false, dataType = "String", paramType = "query"),
})
@PostMapping("/")
public void addUser(@ApiIgnore User user) {
userService.addUser(user);
}
@ApiImplicitParam注释也可用于单参数的情况。
例如:
@ApiOperation(value = "获取用户信息", notes = "根据用户ID获取用户信息")
@ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "int", paramType = "path")
@GetMapping("/{id}")
public User getUser(@PathVariable("id") Long id) {
return userService.getUser(id);
}
5、@ApiModel
用于描述实体类的信息,可以描述实体类的名称、描述、属性等信息。通过@ApiModel注释,可以让API的使用者和开发者快速了解实体类的结构和属性,方便API的测试和调试。
@ApiModel注释常用的属性有:
- value:实体类的名称,必填项。
- description:实体类的描述,可选项。
- parent:该实体类的父类,可选项。
- discriminator:用于多态的标识属性,可选项。
例如:
package com.six.campuseventmanagementsystem.entity;
import com.baomidou.mybatisplus.annotation.IdType;
import com.baomidou.mybatisplus.annotation.TableId;
import com.baomidou.mybatisplus.annotation.TableName;
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.Data;
/**
* 实体类
*/
@ApiModel(value = "广告实体类",description = "广告信息,对应数据库中的tb_ads表")
@Data
@TableName("tb_ads")
public class Ads {
@TableId(type = IdType.AUTO)
@ApiModelProperty(value = "主键,唯一识别一条广告",name = "adsID")
private int adsID;
@ApiModelProperty(value = "赞助商名字",name = "sponsors")
private String sponsors;
@ApiModelProperty(value = "广告类型",name = "adsType")
private String adsType;
@ApiModelProperty(value = "视频广告链接",name = "videoAdress")
private String videoAdress;
@ApiModelProperty(value = "海报广告地址",name = "imageAdress")
private String imageAdress;
@ApiModelProperty(value = "审核状态",name = "state")
private String state;
@ApiModelProperty(value = "赛事id",name = "id")
private int id;
@ApiModelProperty(value = "赛事名称",name = "Items")
private String Items;
}
6、@ApiModelProperty
用于对实体类的属性进行详细的描述。通过@ApiModelProperty注释,可以为实体类的属性添加更多的元数据,包括属性名称、类型、描述、是否必需等信息。
常用的@ApiModelProperty属性包括:
- value:属性的名称,必填项。
- name:属性在实体类中的名称,可选项。
- dataType:属性的数据类型,可选项。如果不填,Swagger会使用Java编译器自动推断。
- required:属性是否是必需的,默认为false。
- example:属性的示例值,可选项。用于指定属性的示例值,方便API的使用者更好地了解API的输入输出参数。
- hidden:属性是否隐藏,默认为false。如果设为true,Swagger会忽略该属性。
例如:
@ApiModel(value = "广告实体类",description = "广告信息,对应数据库中的tb_ads表")
@Data
@TableName("tb_ads")
public class Ads {
@TableId(type = IdType.AUTO)
@ApiModelProperty(value = "主键,唯一识别一条广告",name = "adsID")
private int adsID;
@ApiModelProperty(value = "赞助商名字",name = "sponsors")
private String sponsors;
@ApiModelProperty(value = "广告类型",name = "adsType")
private String adsType;
@ApiModelProperty(value = "视频广告链接",name = "videoAdress")
private String videoAdress;
@ApiModelProperty(value = "海报广告地址",name = "imageAdress")
private String imageAdress;
@ApiModelProperty(value = "审核状态",name = "state")
private String state;
@ApiModelProperty(value = "赛事id",name = "id")
private int id;
@ApiModelProperty(value = "赛事名称",name = "Items")
private String Items;
}