Table of contents
4. @ApiImplicitParams and @ApiImplicitParam
1. Introduction
In modern web development, API annotations are becoming more and more important in the process of connecting interfaces. Developers need to be able to understand each other's API design and implementation in order to work together. As a popular API documentation technology, Swagger2 provides powerful annotation capabilities, which enables developers to record and describe the details and requirements of the API in detail, making it easier to understand and use the API. In this blog, we will explore Swagger2’s API annotation technology and demonstrate how to use it to better interface with front-end developers. We will introduce how to use the annotation feature of Swagger2, how to add parameter and return value annotations to the API, and how to add tags and sample code to the API. After reading this article, you will learn how to use the annotation feature of Swagger2 to make the documentation of the API more clear and easy to understand, making it easier to interface with front-end developers.
2. Notes and usage
1、@Api
Format:
@Api(value = "xx interface", tags = "xx interface")
Used at the beginning of the controller class, explain what interface this class is, and specify basic information such as the name, description, and version of the API.
For example:
2、 @ApiOperation
Format:
@ApiOperation(value = "xxx",notes ="xxx")Basic information used to describe API operations, including operation name, description, HTTP request method, etc. The @ApiOperation annotation usually needs to be added to the API method. Its common attributes include value, notes, response, responseContainer, responseHeaders, tags, etc., among which value and notes are the most important attributes. (Other attributes are optional, these two are required)
value attribute: It specifies the name of the API operation method.
notes attribute: used to explain some specific details of the API. For example: "Description of parameter format, parameter type, parameter range, etc. that need to be passed by the interface", "Description of detailed information such as the interface return value type, whether it can be empty, whether it can be multi-selected, etc." etc. The use of the notes attribute can often reduce API misunderstandings and incorrect calls.
For example:
3、@ApiParam
It is often used when there is a single parameter or a small number of parameters, and is used to describe the parameter information in the API interface. It usually needs to be added to the specific parameters of the API method. Its common attributes include name, value, defaultValue, required, allowableValues, access, allowMultiple, etc.
Commonly used @ApiParam attributes:
- name: parameter name, used to display parameters, required.
- value: A concise description of the parameter, optional.
- defaultValue: The default value of the parameter, optional.
- required: Whether the parameter is required, the default is false.
- allowableValues: Optional values for parameters, used for enumeration type parameter definition, such as limiting the value range of string variables.
- access: The access permission of the parameter. The optional values are PRIVATE, PUBLIC and UNDEFINED, which represent private, public and undefined respectively. The default value is: "PUBLIC".
- allowMultiple: Whether to allow multiple values, for array type parameters. Default is false.
Format:
@ApiParam(value = "xxx", required = true, example = "1")For example:
4. @ApiImplicitParams and @ApiImplicitParam
Used for multi-parameter situations. @ApiImplicitParams contains @ApiImplicitParam, which is used to describe the request parameter list of the API interface by adding multiple @ApiImplicitParam annotations, including parameter name, description, whether it is required, parameter type and other information.
- name: parameter name, used to display parameters, required.
- value: A concise description of the parameter, optional.
- required: Whether the parameter is required, the default is false.
- dataType: parameter type, required.
- paramType: Parameter location, optional options include Query, Header, Path, Body, Form-data, etc. The most commonly used ones are path and query. Path is often used when a single parameter is required and the parameter is required. Query is often used when there are multiple parameters and the parameters are optional.
For example:
@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);
}The @ApiImplicitParam annotation can also be used for single parameters.
For example:
@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
Information used to describe the entity class, which can describe the name, description, attributes and other information of the entity class. Through the @ApiModel annotation, API users and developers can quickly understand the structure and properties of entity classes, which facilitates API testing and debugging.
Commonly used attributes of @ApiModel annotation are:
- value: The name of the entity class, required.
- description: Description of the entity class, optional.
- parent: The parent class of this entity class, optional.
- discriminator: used for polymorphic identification attributes, optional.
For example:
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
Used to describe the attributes of entity classes in detail. Through the @ApiModelProperty annotation, you can add more metadata to the attributes of the entity class, including attribute name, type, description, whether it is required, and other information.
Commonly used @ApiModelProperty properties include:
- value: the name of the attribute, required.
- name: The name of the attribute in the entity class, optional.
- dataType: The data type of the attribute, optional. If left blank, Swagger will use the Java compiler to automatically infer it.
- required: Whether the attribute is required, the default is false.
- example: Example value of the attribute, optional. Example values for specifying attributes to facilitate API users to better understand the input and output parameters of the API.
- hidden: Whether the attribute is hidden, the default is false. If set to true, Swagger will ignore this attribute.
For example:
@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;
}