注解 | 说明 |
---|---|
@Api | 对请求类的说明 |
用于方法上面(说明参数的含义):
注解 | 说明 |
---|---|
@ApiOperation | 方法的说明 |
@ApiImplicitParams、@ApiImplicitParam | 方法的参数的说明;@ApiImplicitParams 用于指定单个参数的说明 |
用于方法上面(返回参数或对象的说明):
注解 | 说明 |
---|---|
@ApiResponses、@ApiResponse | 方法返回值的说明 ;@ApiResponses 用于指定单个参数的说明 |
对象类:
注解 | 说明 |
---|---|
@ApiModel | 用在JavaBean类上,说明JavaBean的 用途 |
@ApiModelProperty | 用在JavaBean类的属性上面,说明此属性的的含议 |
2、@Api:请求类的说明
@Api:放在 请求的类上,与 @Controller 并列,说明类的作用,如用户模块,订单类等。
tags="说明该类的作用"
value="该参数没什么意义,所以不需要配置"
- 1
- 2
- 3
示例:
@Api(tags="订单模块")
@Controller
public class OrderController {
}
- 1
- 2
- 3
- 4
- 5
@Api
其它属性配置:
属性名称 | 备注 |
---|---|
value | url的路径值 |
tags | 如果设置这个值、value的值会被覆盖 |
description | 对api资源的描述 |
basePath | 基本路径 |
position | 如果配置多个Api 想改变显示的顺序位置 |
produces | 如, “application/json, application/xml” |
consumes | 如, “application/json, application/xml” |
protocols | 协议类型,如: http, https, ws, wss. |
authorizations | 高级特性认证时配置 |
hidden | 配置为true ,将在文档中隐藏 |
3、@ApiOperation:方法的说明
@ApiOperation:"用在请求的方法上,说明方法的作用"
value="说明方法的作用"
notes="方法的备注说明"
- 1
- 2
- 3
3.1、@ApiImplicitParams、@ApiImplicitParam:方法参数的说明
@ApiImplicitParams:用在请求的方法上,包含一组参数说明
@ApiImplicitParam:对单个参数的说明
name:参数名
value:参数的汉字说明、解释
required:参数是否必须传
paramType:参数放在哪个地方
· header --> 请求参数的获取:@RequestHeader
· query --> 请求参数的获取:@RequestParam
· path(用于restful接口)--> 请求参数的获取:@PathVariable
· body(请求体)--> @RequestBody User user
· form(普通表单提交)
dataType:参数类型,默认String,其它值dataType="Integer"
defaultValue:参数的默认值
- 1
- 2
- 3
- 4
- 5
- 6
- 7
- 8
- 9
- 10
- 11
- 12
- 13
示列:
@Api(tags="用户模块") @Controller public class UserController {
<span class="token annotation punctuation">@ApiOperation</span><span class="token punctuation">(</span>value<span class="token operator">=</span><span class="token string">"用户登录"</span><span class="token punctuation">,</span>notes<span class="token operator">=</span><span class="token string">"随边说点啥"</span><span class="token punctuation">)</span> <span class="token annotation punctuation">@ApiImplicitParams</span><span class="token punctuation">(</span><span class="token punctuation">{</span> <span class="token annotation punctuation">@ApiImplicitParam</span><span class="token punctuation">(</span>name<span class="token operator">=</span><span class="token string">"mobile"</span><span class="token punctuation">,</span>value<span class="token operator">=</span><span class="token string">"手机号"</span><span class="token punctuation">,</span>required<span class="token operator">=</span><span class="token boolean">true</span><span class="token punctuation">,</span>paramType<span class="token operator">=</span><span class="token string">"form"</span><span class="token punctuation">)</span><span class="token punctuation">,</span> <span class="token annotation punctuation">@ApiImplicitParam</span><span class="token punctuation">(</span>name<span class="token operator">=</span><span class="token string">"password"</span><span class="token punctuation">,</span>value<span class="token operator">=</span><span class="token string">"密码"</span><span class="token punctuation">,</span>required<span class="token operator">=</span><span class="token boolean">true</span><span class="token punctuation">,</span>paramType<span class="token operator">=</span><span class="token string">"form"</span><span class="token punctuation">)</span><span class="token punctuation">,</span> <span class="token annotation punctuation">@ApiImplicitParam</span><span class="token punctuation">(</span>name<span class="token operator">=</span><span class="token string">"age"</span><span class="token punctuation">,</span>value<span class="token operator">=</span><span class="token string">"年龄"</span><span class="token punctuation">,</span>required<span class="token operator">=</span><span class="token boolean">true</span><span class="token punctuation">,</span>paramType<span class="token operator">=</span><span class="token string">"form"</span><span class="token punctuation">,</span>dataType<span class="token operator">=</span><span class="token string">"Integer"</span><span class="token punctuation">)</span> <span class="token punctuation">}</span><span class="token punctuation">)</span> <span class="token annotation punctuation">@PostMapping</span><span class="token punctuation">(</span><span class="token string">"/login"</span><span class="token punctuation">)</span> <span class="token keyword">public</span> JsonResult <span class="token function">login</span><span class="token punctuation">(</span><span class="token annotation punctuation">@RequestParam</span> String mobile<span class="token punctuation">,</span> <span class="token annotation punctuation">@RequestParam</span> String password<span class="token punctuation">,</span> <span class="token annotation punctuation">@RequestParam</span> Integer age<span class="token punctuation">)</span><span class="token punctuation">{</span> <span class="token comment">//...</span> <span class="token keyword">return</span> JsonResult<span class="token punctuation">.</span><span class="token function">ok</span><span class="token punctuation">(</span>map<span class="token punctuation">)</span><span class="token punctuation">;</span> <span class="token punctuation">}</span>
}
- 1
- 2
- 3
- 4
- 5
- 6
- 7
- 8
- 9
- 10
- 11
- 12
- 13
- 14
- 15
- 16
- 17
4、@ApiResponses、@ApiResponse:方法返回值的说明
@ApiResponses:方法返回对象的说明
@ApiResponse:每个参数的说明
code:数字,例如400
message:信息,例如"请求参数没填好"
response:抛出异常的类
- 1
- 2
- 3
- 4
- 5
示例:
@Api(tags="用户模块") @Controller public class UserController {
<span class="token annotation punctuation">@ApiOperation</span><span class="token punctuation">(</span><span class="token string">"获取用户信息"</span><span class="token punctuation">)</span> <span class="token annotation punctuation">@ApiImplicitParams</span><span class="token punctuation">(</span><span class="token punctuation">{</span> <span class="token annotation punctuation">@ApiImplicitParam</span><span class="token punctuation">(</span>paramType<span class="token operator">=</span><span class="token string">"query"</span><span class="token punctuation">,</span> name<span class="token operator">=</span><span class="token string">"userId"</span><span class="token punctuation">,</span> dataType<span class="token operator">=</span><span class="token string">"String"</span><span class="token punctuation">,</span> required<span class="token operator">=</span><span class="token boolean">true</span><span class="token punctuation">,</span> value<span class="token operator">=</span><span class="token string">"用户Id"</span><span class="token punctuation">)</span> <span class="token punctuation">}</span><span class="token punctuation">)</span> <span class="token annotation punctuation">@ApiResponses</span><span class="token punctuation">(</span><span class="token punctuation">{</span> <span class="token annotation punctuation">@ApiResponse</span><span class="token punctuation">(</span>code <span class="token operator">=</span> <span class="token number">400</span><span class="token punctuation">,</span> message <span class="token operator">=</span> <span class="token string">"请求参数没填好"</span><span class="token punctuation">)</span><span class="token punctuation">,</span> <span class="token annotation punctuation">@ApiResponse</span><span class="token punctuation">(</span>code <span class="token operator">=</span> <span class="token number">404</span><span class="token punctuation">,</span> message <span class="token operator">=</span> <span class="token string">"请求路径没有或页面跳转路径不对"</span><span class="token punctuation">)</span> <span class="token punctuation">}</span><span class="token punctuation">)</span> <span class="token annotation punctuation">@ResponseBody</span> <span class="token annotation punctuation">@RequestMapping</span><span class="token punctuation">(</span><span class="token string">"/list"</span><span class="token punctuation">)</span> <span class="token keyword">public</span> JsonResult <span class="token function">list</span><span class="token punctuation">(</span><span class="token annotation punctuation">@RequestParam</span> String userId<span class="token punctuation">)</span> <span class="token punctuation">{</span> <span class="token punctuation">.</span><span class="token punctuation">.</span><span class="token punctuation">.</span> <span class="token keyword">return</span> JsonResult<span class="token punctuation">.</span><span class="token function">ok</span><span class="token punctuation">(</span><span class="token punctuation">)</span><span class="token punctuation">.</span><span class="token function">put</span><span class="token punctuation">(</span><span class="token string">"page"</span><span class="token punctuation">,</span> pageUtil<span class="token punctuation">)</span><span class="token punctuation">;</span> <span class="token punctuation">}</span>
}
- 1
- 2
- 3
- 4
- 5
- 6
- 7
- 8
- 9
- 10
- 11
- 12
- 13
- 14
- 15
- 16
- 17
- 18
- 19
5、@ApiModel:用于JavaBean上面,表示一个JavaBean(如:响应数据)的信息
@ApiModel:用于JavaBean的类上面,表示此 JavaBean 整体的信息
(这种一般用在post创建的时候,使用 @RequestBody 这样的场景,
请求参数无法使用 @ApiImplicitParam 注解进行描述的时候 )
- 1
- 2
- 3
5.1、@ApiModelProperty:用在JavaBean类的属性上面,说明属性的含义
示例:
@ApiModel(description= "返回响应数据") public class RestMessage implements Serializable{
<span class="token annotation punctuation">@ApiModelProperty</span><span class="token punctuation">(</span>value <span class="token operator">=</span> <span class="token string">"是否成功"</span><span class="token punctuation">)</span> <span class="token keyword">private</span> <span class="token keyword">boolean</span> success<span class="token operator">=</span><span class="token boolean">true</span><span class="token punctuation">;</span> <span class="token annotation punctuation">@ApiModelProperty</span><span class="token punctuation">(</span>value <span class="token operator">=</span> <span class="token string">"返回对象"</span><span class="token punctuation">)</span> <span class="token keyword">private</span> Object data<span class="token punctuation">;</span> <span class="token annotation punctuation">@ApiModelProperty</span><span class="token punctuation">(</span>value <span class="token operator">=</span> <span class="token string">"错误编号"</span><span class="token punctuation">)</span> <span class="token keyword">private</span> Integer errCode<span class="token punctuation">;</span> <span class="token annotation punctuation">@ApiModelProperty</span><span class="token punctuation">(</span>value <span class="token operator">=</span> <span class="token string">"错误信息"</span><span class="token punctuation">)</span> <span class="token keyword">private</span> String message<span class="token punctuation">;</span> <span class="token comment">/* getter/setter 略*/</span>
}
- 1
- 2
- 3
- 4
- 5
- 6
- 7
- 8
- 9
- 10
- 11
- 12
- 13
- 14
http://localhost:5680/zxmall/swagger-ui.html
</div>