目前项目已经替换为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;