基于swagger2的api注释

     

目录

一、导语

二、注释及用法

1、@Api

2、 @ApiOperation

3、@ApiParam

4、 @ApiImplicitParams和@ApiImplicitParam

5、@ApiModel

6、@ApiModelProperty

一、导语

        在现代的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;
}