前后端分离swagger接口文档常见处理

1、swagger2 注解整体说明

用于controller类上：

注解	说明
@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>