swagger注释API详细说明

admin 08-15 00:57 63次浏览

API详细说明

注释汇总

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

@RequestMapping此注解的推荐配置
value
method
produces

示例： @ApiOperation("信息软删除") @ApiResponses({ @ApiResponse(code = CommonStatus.OK, message = "操作成功"), @ApiResponse(code = CommonStatus.EXCEPTION, message = "服务器内部异常"), @ApiResponse(code = CommonStatus.FORBIDDEN, message = "权限不足") }) @ApiImplicitParams({ @ApiImplicitParam(paramType = "query", dataType = "Long", name = "id", value = "信息id", required = true) }) @RequestMapping(value = "/remove.json", method = RequestMethod.GET, produces = MediaType.APPLICATION_JSON_UTF8_VALUE) public RestfulProtocol remove(Long id) { @ApiModelProperty(value = "标题") private String title; @ApiImplicitParam 属性取值作用paramType 查询参数类型 path以地址的形式提交数据 query直接跟参数完成自动映射赋值 body以流的形式提交仅支持POST header参数在request headers 里边提交 form以form表单的形式提交仅支持POSTdataType 参数的数据类型只作为标志说明，并没有实际验证 Long String name 接收参数名value 接收参数的意义描述required 参数是否必填 true必填 false非必填defaultValue 默认值paramType 示例详解

path

@RequestMapping(value = "/findById1/{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 = "/findById3", method = RequestMethod.POST, produces = MediaType.APPLICATION_JSON_UTF8_VALUE, consumes = MediaType.APPLICATION_JSON_VALUE) @RequestBody MessageParam param 提交的参数是这个对象的一个json，然后会自动解析到对应的字段上去，也可以通过流的形式接收当前的请求数据，但是这个和上面的接收方式仅能使用一个（用@RequestBody之后流就会关闭了） 接收对象传参的例子

在POJO上增加

package com.zhongying.api.model.base;import io.swagger.annotations.ApiModel;import io.swagger.annotations.ApiModelProperty;@ApiModel(value="对象模型")public class DemoDoctor{ @ApiModelProperty(value="id" ,required=true) private Integer id; @ApiModelProperty(value="姓名" ,required=true) private String name; public Integer getId() { return id; } public void setId(Integer id) { this.id = id; } public String getName() { return name; } public void setName(String name) { this.name = name; } @Override public String toString() { return "DemoDoctor [id=" + id + ", name=" + name + "]"; } }

注意：在后台采用对象接收参数时，Swagger自带的工具采用的是JSON传参，测试时需要在参数上加入@RequestBody,正常运行采用form或URL提交时候请删除。

header

@ApiImplicitParams({ @ApiImplicitParam(paramType = "header", dataType = "Long", name = "id", value = "信息id", required = true) }) 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 = "/findById5", method = RequestMethod.POST, produces = MediaType.APPLICATION_JSON_UTF8_VALUE, consumes = MediaType.APPLICATION_FORM_URLENCODED_VALUE)

java身份证合法性校验工具类实例代码

apimodelproperty注解在实体类上干嘛的,@Apimodel swagger注解教程,swagger api注解