Swagger配置API接口文档参数说明、返回值说明

2年前 (2022) 程序员胖胖胖虎阿
360 0 0

Swagger2.X注解

常用到的注解有:

作用范围 API 使用位置
协议集描述 @Api 用于controller类上
协议描述 @ApiOperation 用在controller的方法上
非对象参数集 @ApiImplicitParams 用在controller的方法上
非对象参数描述 @ApiImplicitParam 用在@ApiImplicitParams的方法里边
对象参数描述 @ApiParam 用在@ApiImplicitParams的方法里边,定义接收的参数形式
描述返回对象的意义 @ApiModel 用在返回对象类上
对象属性 @ApiModelProperty 用在参数对象的字段上
Response集 @ApiResponses 用在controller的方法上
Response @ApiResponse 用在 @ApiResponses里边
Response @ResponseHeader

1、实体类注解

@ApiModel(value = "统计查询VO对象")

2、字段注解

@ApiModelProperty(value = "区域代码")

例子

package com.auto.vo;

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.Data;

/**
 * <p>
 * 统计查询 VO对象
 * </p>
 *
 * @author QC
 * @since 2022-07-12
 */
@Data
@ApiModel(value = "统计查询VO对象")
public class QCParamVO {
    @ApiModelProperty(value = "区域代码", example = "6000")
    private String areaCode;

    @ApiModelProperty(value = "企业编码", example = "大利九发(深圳)科技信息有限公司")
    private String companyCode;

    @ApiModelProperty(value = "企业名称", example = "001")
    private String companyName;

   
}
3、Controller类注解
@Api(value = "ibestidea-com", tags = "统计查询接口")

4、Controller类的方法注解

@ApiOperation(value = "流量统计", response = QCResponse.class, notes = "流量统计,默认加载查询全数据")

response = QCResponse.class是配置响应类,在前端文档中会形成响应示例方便查看,和上面实体类配置也是一样的。

@ApiParam(name = "QCParamVO", value = "查询条件对象", required = true) 

例子

@RestController
@AllArgsConstructor
@RequestMapping("/v1/ibestidea-com")
@Api(value = "ibestidea.com", tags = "列表查询接口")
public class QCController {
    @ApiOperation(value = "信息列表", notes = "信息列表", response = QCResponse.class)
    @PostMapping(value = "/query-list")
    public Result queryList(@ApiParam(name = "QCParamVO", value = "查询条件对象", required = true) @RequestBody QCParamVO qCParamVO,
                                         @ApiParam(name = "pageNumber", value = "页码", defaultValue = "1", required = false) @RequestParam(required = false, defaultValue = "1") int pageNumber,
                                         @ApiParam(name = "pageSize", value = "每页条数", defaultValue = "10", required = false) @RequestParam(required = false, defaultValue = "10") int pageSize) {
    }
}

Swagger配置API接口文档参数说明、返回值说明


 参考文献

1、Swagger2.X注解 - 走看看

版权声明:程序员胖胖胖虎阿 发表于 2022年11月21日 下午8:16。
转载请注明:Swagger配置API接口文档参数说明、返回值说明 | 胖虎的工具箱-编程导航

相关文章

暂无评论

暂无评论...