Swagger常用注解

目前项目已经替换为knife4j了:https://www.jianshu.com/p/48d9473de9c8(个人比较喜欢knife4j的ui风格,而且用起来比较方便)

下面介绍一些在开发过程中通常用的Swagger注解。

1、@Api

说明每个controller层控制类的作用,即每个请求类
属性:tags:描述该类的作用

2、@RestController

它是复合注解,代表的是一个控制器,由于它同时拥有@Controller和@ResponseBody的作用,所在如果要返回JSON数据,则不需要在方法上面加@ResponseBody注解,但是它不能返回jsp、html页面

3、@RequestMapping、@GetMapping、@PostMapping、@PutMapping、@DeleteMapping

定义前端访问的url,可以写在控制类上,也可以写在控制类汇总的方法上面,常用的的写在控制类上面,一般会与它的衍生注解组合使用:
@GetMapping 查询请求
@PostMapping 添加请求
@PutMapping 修改请求
@DeleteMapping 删除请求

4、@ApiOperation

作用在控制类中的每个方法上,说明该类的作用
value:说明该类的作用
notes:详细说明
以上这几个注解在代码中的使用例子如下:

/**
 * Description: 立案审批
 *
 * @author ZhuZiKai
 * @date 2019/9/13 0013
 */
@Api(tags = {"立案受理"})
@RestController
@RequestMapping(value = "/case")
public class AcceptanceController extends BaseController {
    @Autowired
    private AcceptanceService acceptanceService;
    @Autowired
    private AsyncTask asyncTask;
    @Autowired
    private BaseStatisticsImpl baseStatistics;
    
    @ApiOperation(value = "案件基本信息录入",notes="")
    @PostMapping(value = "/acceptance/inputBaseInfo")
    public BaseResp inputBaseInfo(@ApiParam(value = "案件受理对象", required = false) Acceptance acceptance) {

swagger-ui展示结果如下:
在这里插入图片描述

5、@ApiParam

@ApiParam作用于请求方法上,定义api参数的注解,属性有:
name:api参数的英文名
value:api参数的描述
required:true表示参数必输,false标识参数非必输,默认为非必输
此注解通常与@RequestParam或者@PathVariable集合使用,因为它的作用只是定义每个参数(因此可以不使用,但是为了方便测试,加上效果更好),如果要获取前端的参数还需要通过@RequestParam或者@PathVariable来获取

6、@PathVariable

获取get请求url路径上的参数,即参数绑定的作用,通俗的说是url中"?"前面绑定的参数
代码示例:

/**
     * 根据案件Id获取案件
     * @param caseId 案件编号
     * @return
     */
    @GetMapping(value = "/Close/getCases/{caseId}")
    public BaseResp getCases(@ApiParam(name = "String", value = "案件编号", required = true) @PathVariable("caseId") String caseId) {
        Admin currentUser = findCurrentUser();
        List<PageData> caseApprovals = closeService.getCases(currentUser, caseId);
        return new BaseResp(ResultStatus.SUCCESS, caseApprovals);
    }

测试示例:
在这里插入图片描述
请求url示例:http://127.0.0.1:8081/case/Close/getCases/2019091508
这里的获取参数的类型下面会说一下有几种形式。

7、@RequestParam

获取前端传过来的参数,可以是get、post请求,通俗的说是url中"?"后面拼接的每个参数
代码示例:

/**
     * 根据案件Id获取案件
     * @param caseId 案件编号
     * @return
     */
    @GetMapping(value = "/Close/getCases)
    public BaseResp getCases(@ApiParam(name = "String", value = "案件编号", required = true) @RequestParam("caseId") String caseId) {
        Admin currentUser = findCurrentUser();
        List<PageData> caseApprovals = closeService.getCases(currentUser, caseId);
        return new BaseResp(ResultStatus.SUCCESS, caseApprovals);
    }

测试示例:
请求url示例:http://127.0.0.1:8081/case/Close/getCases?caseId=2019091508

8、@RequestBody

@RequestBody接受的是一个json对象的字符串,而不是Json对象,在请求时往往都是Json对象,用JSON.stringify(data)的方式就能将对象变成json字符串。如果使用@RequestBody出现Content type ‘application/x-www-form-urlencoded;charset=UTF-8’ not supported 的时候。可能是如下问题
在这里插入图片描述
所以当前端传的是Json对象字符串时,后端接口用@RequestBody接收参数

 /**
     * 调查经过描述录入
     *
     * @param investigationReport
     * @return
     */
    @ApiOperation(value = "调查经过描述录入")
    @PostMapping(value = "/details/inputIllegalFacts")
    public BaseResp illegalFacts(@ApiParam(value = "案件调查终结报告对象") @RequestBody InvestigationReport investigationReport) {
        try {

这时候swagger怎么获取都对象里面每个参数的类型以及说明呢,这里介绍两个用于对象上的注解@ApiModel,@ApiModelProperty。

9、@ApiModel

@ApiModel 用在类上,表示对类进行说明,用于实体类中的参数接收说明。使用方式代码如下所示。

/**
 * Description: 案件调查终结报告
 *
 * @author ZhuZiKai
 * @date 2020/2/14 0014
 */
@Data
@Table(name = "hz_ac_investigation_report")
@ApiModel(value = "com.terabits.examinationcase.meta.po.InvestigationReport", description = "案件调查终结报告对象")
public class InvestigationReport {
}
10、@ApiModelProperty

@ApiModelProperty() 用于字段,表示对 model 属性的说明。使用方式代码如下所示。

@Data
@Table(name = "hz_ac_investigation_report")
@ApiModel(value = "com.terabits.examinationcase.meta.po.InvestigationReport", description = "案件调查终结报告对象")
public class InvestigationReport {
    @ApiModelProperty(value = "id", dataType = "Integer")
    private Integer id;

    @ApiModelProperty(value = "案件编号", dataType = "String")
    private String caseId;
    
    @ApiModelProperty(value = "主办人编号", dataType = "Integer")

    private Integer adminId;

swagger接口展示
在这里插入图片描述

11、 @ApiImplicitParams、@ApiImplicitParam

定义参数的注解除了@ApiParam之外,这两个注解也可以定义参数,一般用于对每个参数单独定义
①、@ApiImplicitParams定义一组参数
②、@ApiImplicitParam写在@ApiImplicitParams中,定义每个参数的信息,属性为:
name:参数英文名称
value:参数中文名称
paramType:调用的url 参数形式,“query”为问号"?"后面的拼接参数,“path”为绑定的参数,“header”为request请求头参数,“form”为表单提交参数,“body”为对象参数,仅支持post
代码示例:

/**
     * 结案案件查询列表
     *
     * @param caseId
     * @param beginTime
     * @param endTime
     * @param decisionBeginTime
     * @param decisionEndTime
     * @return
     */
    @ApiOperation(value = "结案案件查询列表")
    @ApiImplicitParams({
            @ApiImplicitParam(paramType = "query", dataType = "String", name = "caseId", value = "案件id", required = false),
            @ApiImplicitParam(paramType = "query", dataType = "String", name = "beginTime", value = "结案开始时间", required = false),
            @ApiImplicitParam(paramType = "query", dataType = "String", name = "endTime", value = "结案结束时间", required = false),
            @ApiImplicitParam(paramType = "query", dataType = "String", name = "decisionBeginTime", value = "决定书寄出开始时间", required = false),
            @ApiImplicitParam(paramType = "query", dataType = "String", name = "decisionEndTime", value = "决定书寄出结束时间", required = false)
    })
    @GetMapping(value = "/case/Close/getCases")
    public BaseResp getCases(@RequestParam String caseId, @RequestParam String beginTime, @RequestParam String endTime, @RequestParam String decisionBeginTime, @RequestParam String decisionEndTime) {
        try {
            Admin currentUser = findCurrentUser();
            List<PageData> caseApprovals = closeService.getCases(currentUser, caseId, beginTime, endTime, decisionBeginTime, decisionEndTime);
            return new BaseResp(ResultStatus.SUCCESS, caseApprovals);
        } catch (Exception e) {
            EXCEPTIONLOGGER.error("", e);
        }
        return new BaseResp(ResultStatus.FAIL);
    }

测试示例:
在这里插入图片描述

@ApiImplicitParam
属性取值作用
paramType查询参数类型
path以地址的形式提交数据
query直接跟参数完成自动映射赋值
body以流的形式提交 仅支持POST
header参数在request headers 里边提交
form以form表单的形式提交 仅支持POST
dataType参数的数据类型 只作为标志说明,并没有实际验证
Long
String
name接收参数名
value接收参数的意义描述
required参数是否必填
true必填
false非必填
defaultValue默认值
@ApiImplicitParam(paramType = "query", dataType = "String", name = "caseId", value = "案件id", required = false),
paramType 示例详解
path
@RequestMapping(value = "/getCases/{id}", method = RequestMethod.GET, produces = MediaType.APPLICATION_JSON_UTF8_VALUE)
 
 @PathVariable(name = "id") Long id
body
@ApiImplicitParams({ @ApiImplicitParam(paramType = "body", dataType = "MessageParam", name = "param", value = "信息参数", required = true) })
 @RequestMapping(value = "/getCases", method = RequestMethod.POST, produces = MediaType.APPLICATION_JSON_UTF8_VALUE, consumes = MediaType.APPLICATION_JSON_VALUE)
 
 @RequestBody MessageParam param
 
 提交的参数是这个对象的一个json,然后会自动解析到对应的字段上去,也可以通过流的形式接收当前的请求数据,但是这个和上面的接收方式仅能使用一个(用@RequestBody之后流就会关闭了)
 
header
@ApiImplicitParams({ @ApiImplicitParam(paramType = "header", dataType = "Long", name = "id", value = "信息id", required = true) })
 //参数在request headers 请求头中 
  String idstr = request.getHeader("id");
       if (StringUtils.isNumeric(idstr)) {
           id = Long.parseLong(idstr);
       }
      
Form
@ApiImplicitParams({ @ApiImplicitParam(paramType = "form", dataType = "Long", name = "id", value = "信息id", required = true) })
 @RequestMapping(value = "/getCases", method = RequestMethod.POST, produces = MediaType.APPLICATIO
12、ApiResponse 和 ApiResponses

@ApiResponse 用于方法上,说明接口响应的一些信息;@ApiResponses 组装了多个 @ApiResponse。使用方式代码如下所示。

@ApiOperation(value = "案件基本信息录入")
    @ApiResponses({@ApiResponse(code = 200, message = "操作成功"),
            @ApiResponse(code = 400, message = "请求中有语法错误,或不能满足请求"),
            @ApiResponse(code = 401, message = "未授权客户端访问数据"),
            @ApiResponse(code = 403, message = "服务器内部异常"),
            @ApiResponse(code = 404, message = "服务器找不到给定资源;接口不存在"),
            @ApiResponse(code = 500, message = "服务器不能完成请求")
    })
    @ApiImplicitParams({
            @ApiImplicitParam(paramType = "body", dataType = "Acceptance", name = "acceptance", value = "案件受理对象", required = false)
    })
    @PostMapping(value = "/acceptance/inputBaseInfo")
    public BaseResp inputBaseInfo(@RequestBody Acceptance acceptance) {

总结:基本上日常常用注解整理一下就是这样了,如下实例:(@ApiResponses注解写在每个接口的话,个人觉得代码很臃肿,所以省略了)


/**
 * Description: 案件查询
 *
 * @author ZhuZiKai
 * @date 2019/10/14 0014
 */
@Api(tags = {"结案案件查询"})
@RestController
@RequestMapping(value = "/case")
public class CaseInfoController extends BaseController {
    @Autowired
    private CloseService closeService;

    /**
     * 结案案件查询列表
     *
     * @param caseId
     * @param decisionBeginTime
     * @param decisionEndTime
     * @return
     */
    @ApiOperation(value = "结案案件查询列表",notes = "")
    @ApiImplicitParams({
            @ApiImplicitParam(paramType = "query", dataType = "String", name = "caseId", value = "案件编号", required = false),
            @ApiImplicitParam(paramType = "query", dataType = "String", name = "decisionBeginTime", value = "决定书寄出时间", required = false),
            @ApiImplicitParam(paramType = "query", dataType = "String", name = "decisionEndTime", value = "决定书寄出时间", required = false)
    })
    @GetMapping(value = "/Close/getCases")
    public BaseResp getCases(@RequestParam(value = "caseId") String caseId, @RequestParam(value = "decisionBeginTime") String decisionBeginTime, @RequestParam(value = "decisionEndTime") String decisionEndTime) {
        try {
            Admin currentUser = findCurrentUser();
            List<PageData> caseApprovals = closeService.getCases(currentUser, caseId, decisionBeginTime, decisionEndTime);
            return new BaseResp(ResultStatus.SUCCESS, caseApprovals);
        } catch (Exception e) {
            EXCEPTIONLOGGER.error("", e);
        }
        return new BaseResp(ResultStatus.FAIL);
    }
接收参数为json字符串,接口参数用对象接收时实例:
/**
     * 调查经过描述录入
     *
     * @param investigationReport
     * @return
     */
    @ApiOperation(value = "调查经过描述录入",notes = "")
    @PostMapping(value = "/details/inputIllegalFacts")
    public BaseResp illegalFacts(@ApiParam(value = "案件调查终结报告对象") @RequestBody InvestigationReport investigationReport) {
        try {
            Integer integer = caseInformationService.inputIllegalFacts(investigationReport);
            if (integer == 1) {
                return new BaseResp(ResultStatus.SUCCESS);
            }
            return new BaseResp(ResultStatus.FAIL);
        } catch (Exception e) {
            EXCEPTIONLOGGER.error("", e);
        }
        return new BaseResp(ResultStatus.FAIL);
    }
对象类实例
/**
 * Description: 案件调查终结报告
 *
 * @author ZhuZiKai
 * @date 2020/2/14 0014
 */
@Data
@Table(name = "hz_ac_investigation_report")
@ApiModel(value = "com.terabits.examinationcase.meta.po.InvestigationReport", description = "案件调查终结报告对象")
public class InvestigationReport {
    @ApiModelProperty(value = "id", dataType = "Integer")
    private Integer id;

    @ApiModelProperty(value = "案件编号", dataType = "String")
    private String caseid;

    @ApiModelProperty(value = "主办人编号", dataType = "Integer")

    private Integer adminid;
  • 1
    点赞
  • 5
    收藏
    觉得还不错? 一键收藏
  • 打赏
    打赏
  • 0
    评论
评论
添加红包

请填写红包祝福语或标题

红包个数最小为10个

红包金额最低5元

当前余额3.43前往充值 >
需支付:10.00
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包

打赏作者

_Romeo

你的鼓励将是我创作的最大动力

¥1 ¥2 ¥4 ¥6 ¥10 ¥20
扫码支付:¥1
获取中
扫码支付

您的余额不足,请更换扫码支付或充值

打赏作者

实付
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明:

1.余额是钱包充值的虚拟货币,按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载,可以购买VIP、付费专栏及课程。

余额充值