Swagger常用注解

灰太狼 2023-07-08 12:29 2阅读 0赞

目前项目已经替换为knife4j了：[https://www.jianshu.com/p/48d9473de9c8][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展示结果如下：  
![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L051bWJlcl9vbmVFbmdpbmVlcg_size_16_color_FFFFFF_t_70]

##### 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);
        }

测试示例：  
![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L051bWJlcl9vbmVFbmdpbmVlcg_size_16_color_FFFFFF_t_70 1]  
请求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** 的时候。可能是如下问题  
![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L051bWJlcl9vbmVFbmdpbmVlcg_size_16_color_FFFFFF_t_70 2]  
所以当前端传的是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 用在类上，表示对类进行说明，用于实体类中的参数接收说明。使用方式代码如下所示。

##### 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接口展示  
![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L051bWJlcl9vbmVFbmdpbmVlcg_size_16_color_FFFFFF_t_70 3]

##### 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);
        }

测试示例：  
![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L051bWJlcl9vbmVFbmdpbmVlcg_size_16_color_FFFFFF_t_70 4]

##### @ApiImplicitParam #####

<table> 
 <thead> 
  <tr> 
   <th>属性</th> 
   <th>取值</th> 
   <th>作用</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td>paramType</td> 
   <td></td> 
   <td>查询参数类型</td> 
  </tr> 
  <tr> 
   <td></td> 
   <td>path</td> 
   <td>以地址的形式提交数据</td> 
  </tr> 
  <tr> 
   <td></td> 
   <td>query</td> 
   <td>直接跟参数完成自动映射赋值</td> 
  </tr> 
  <tr> 
   <td></td> 
   <td>body</td> 
   <td>以流的形式提交 仅支持POST</td> 
  </tr> 
  <tr> 
   <td></td> 
   <td>header</td> 
   <td>参数在request headers 里边提交</td> 
  </tr> 
  <tr> 
   <td></td> 
   <td>form</td> 
   <td>以form表单的形式提交 仅支持POST</td> 
  </tr> 
  <tr> 
   <td>dataType</td> 
   <td></td> 
   <td>参数的数据类型 只作为标志说明，并没有实际验证</td> 
  </tr> 
  <tr> 
   <td></td> 
   <td>Long</td> 
   <td></td> 
  </tr> 
  <tr> 
   <td></td> 
   <td>String</td> 
   <td></td> 
  </tr> 
  <tr> 
   <td>name</td> 
   <td></td> 
   <td>接收参数名</td> 
  </tr> 
  <tr> 
   <td>value</td> 
   <td></td> 
   <td>接收参数的意义描述</td> 
  </tr> 
  <tr> 
   <td>required</td> 
   <td></td> 
   <td>参数是否必填</td> 
  </tr> 
  <tr> 
   <td></td> 
   <td>true</td> 
   <td>必填</td> 
  </tr> 
  <tr> 
   <td>false</td> 
   <td></td> 
   <td>非必填</td> 
  </tr> 
  <tr> 
   <td>defaultValue</td> 
   <td></td> 
   <td>默认值</td> 
  </tr> 
  <tr> 
   <td></td> 
   <td></td> 
   <td></td> 
  </tr> 
 </tbody> 
</table>

@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;

[https_www.jianshu.com_p_48d9473de9c8]: https://www.jianshu.com/p/48d9473de9c8
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L051bWJlcl9vbmVFbmdpbmVlcg_size_16_color_FFFFFF_t_70]: https://img-blog.csdnimg.cn/20200226165352760.png?x-oss-process=image/watermark,type_ZmFuZ3poZW5naGVpdGk,shadow_10,text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L051bWJlcl9vbmVFbmdpbmVlcg==,size_16,color_FFFFFF,t_70
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L051bWJlcl9vbmVFbmdpbmVlcg_size_16_color_FFFFFF_t_70 1]: https://img-blog.csdnimg.cn/20200226170548785.png?x-oss-process=image/watermark,type_ZmFuZ3poZW5naGVpdGk,shadow_10,text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L051bWJlcl9vbmVFbmdpbmVlcg==,size_16,color_FFFFFF,t_70
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L051bWJlcl9vbmVFbmdpbmVlcg_size_16_color_FFFFFF_t_70 2]: https://img-blog.csdnimg.cn/20200227101603520.png?x-oss-process=image/watermark,type_ZmFuZ3poZW5naGVpdGk,shadow_10,text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L051bWJlcl9vbmVFbmdpbmVlcg==,size_16,color_FFFFFF,t_70
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L051bWJlcl9vbmVFbmdpbmVlcg_size_16_color_FFFFFF_t_70 3]: https://img-blog.csdnimg.cn/2020022710253254.png?x-oss-process=image/watermark,type_ZmFuZ3poZW5naGVpdGk,shadow_10,text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L051bWJlcl9vbmVFbmdpbmVlcg==,size_16,color_FFFFFF,t_70
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L051bWJlcl9vbmVFbmdpbmVlcg_size_16_color_FFFFFF_t_70 4]: https://img-blog.csdnimg.cn/20200226171429451.png?x-oss-process=image/watermark,type_ZmFuZ3poZW5naGVpdGk,shadow_10,text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L051bWJlcl9vbmVFbmdpbmVlcg==,size_16,color_FFFFFF,t_70