swagger2 注解说明

灰太狼 2024-04-18 10:47 88阅读 0赞

本文链接： [https://blog.csdn.net/xiaojin21cen/article/details/78654652][https_blog.csdn.net_xiaojin21cen_article_details_78654652]

### 文章目录 ###

*  1、swagger2 注解整体说明
 *  2、@Api：请求类的说明
 *  3、@ApiOperation：方法的说明
 *   *   *  3.1、@ApiImplicitParams、@ApiImplicitParam：方法参数的说明
 *  4、@ApiResponses、@ApiResponse：方法返回值的说明
 *  5、@ApiModel：用于JavaBean上面，表示一个JavaBean（如：响应数据）的信息
 *   *  5.1、@ApiModelProperty：用在JavaBean类的属性上面，说明属性的含义

# 1、swagger2 注解整体说明 #

**用于controller类上：**

<table> 
 <thead> 
 <tr> 
 <th>注解</th> 
 <th>说明</th> 
 </tr> 
 </thead> 
 <tbody> 
 <tr> 
 <td>@Api</td> 
 <td>对请求类的说明</td> 
 </tr> 
 </tbody> 
</table>

**用于方法上面（说明参数的含义）：**

<table> 
 <thead> 
 <tr> 
 <th align="left">注解</th> 
 <th align="left">说明</th> 
 </tr> 
 </thead> 
 <tbody> 
 <tr> 
 <td align="left">@ApiOperation</td> 
 <td align="left">方法的说明</td> 
 </tr> 
 <tr> 
 <td align="left">@ApiImplicitParams、@ApiImplicitParam</td> 
 <td align="left">方法的参数的说明；@ApiImplicitParams 用于指定单个参数的说明</td> 
 </tr> 
 </tbody> 
</table>

**用于方法上面（返回参数或对象的说明）：**

<table> 
 <thead> 
 <tr> 
 <th align="left">注解</th> 
 <th align="left">说明</th> 
 </tr> 
 </thead> 
 <tbody> 
 <tr> 
 <td align="left">@ApiResponses、@ApiResponse</td> 
 <td align="left">方法返回值的说明 ；@ApiResponses 用于指定单个参数的说明</td> 
 </tr> 
 </tbody> 
</table>

**对象类：**

<table> 
 <thead> 
 <tr> 
 <th align="left">注解</th> 
 <th align="left">说明</th> 
 </tr> 
 </thead> 
 <tbody> 
 <tr> 
 <td align="left">@ApiModel</td> 
 <td align="left">用在JavaBean类上，说明JavaBean的 用途</td> 
 </tr> 
 <tr> 
 <td align="left">@ApiModelProperty</td> 
 <td align="left">用在JavaBean类的属性上面，说明此属性的的含议</td> 
 </tr> 
 </tbody> 
</table>

# 2、@Api：请求类的说明 #

@Api：放在 请求的类上，与 @Controller 并列，说明类的作用，如用户模块，订单类等。
    	tags="说明该类的作用"
    	value="该参数没什么意义，所以不需要配置"
    
     
      
     
      
       1
       2
       3

示例：

@Api(tags="订单模块")
    @Controller
    public class OrderController {

*  1
 *  2
 *  3
 *  4
 *  5

`@Api` 其它属性配置：

<table> 
 <thead> 
 <tr> 
 <th>属性名称</th> 
 <th>备注</th> 
 </tr> 
 </thead> 
 <tbody> 
 <tr> 
 <td>value</td> 
 <td>url的路径值</td> 
 </tr> 
 <tr> 
 <td>tags</td> 
 <td>如果设置这个值、value的值会被覆盖</td> 
 </tr> 
 <tr> 
 <td>description</td> 
 <td>对api资源的描述</td> 
 </tr> 
 <tr> 
 <td>basePath</td> 
 <td>基本路径</td> 
 </tr> 
 <tr> 
 <td>position</td> 
 <td>如果配置多个Api 想改变显示的顺序位置</td> 
 </tr> 
 <tr> 
 <td>produces</td> 
 <td>如, “application/json, application/xml”</td> 
 </tr> 
 <tr> 
 <td>consumes</td> 
 <td>如, “application/json, application/xml”</td> 
 </tr> 
 <tr> 
 <td>protocols</td> 
 <td>协议类型，如: http, https, ws, wss.</td> 
 </tr> 
 <tr> 
 <td>authorizations</td> 
 <td>高级特性认证时配置</td> 
 </tr> 
 <tr> 
 <td>hidden</td> 
 <td>配置为true ，将在文档中隐藏</td> 
 </tr> 
 </tbody> 
</table>

# 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 { 
 @ApiOperation(value="用户登录",notes="随边说点啥")
 @ApiImplicitParams({
 	@ApiImplicitParam(name="mobile",value="手机号",required=true,paramType="form"),
 	@ApiImplicitParam(name="password",value="密码",required=true,paramType="form"),
 	@ApiImplicitParam(name="age",value="年龄",required=true,paramType="form",dataType="Integer")
 })
 @PostMapping("/login")
 public JsonResult login(@RequestParam String mobile, @RequestParam String password,
 @RequestParam Integer age){
 	//...
 return JsonResult.ok(map);
 }

*  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 { 
 @ApiOperation("获取用户信息")
 @ApiImplicitParams({
 	@ApiImplicitParam(paramType="query", name="userId", dataType="String", required=true, value="用户Id")
 }) 
 @ApiResponses({
 	@ApiResponse(code = 400, message = "请求参数没填好"),
 	@ApiResponse(code = 404, message = "请求路径没有或页面跳转路径不对")
 }) 
 @ResponseBody
 @RequestMapping("/list")
 public JsonResult list(@RequestParam String userId) {
 	...
 	return JsonResult.ok().put("page", pageUtil);
 }

*  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{ 
 @ApiModelProperty(value = "是否成功")
 private boolean success=true;
 @ApiModelProperty(value = "返回对象")
 private Object data;
 @ApiModelProperty(value = "错误编号")
 private Integer errCode;
 @ApiModelProperty(value = "错误信息")
 private String message;
 	
 /* getter/setter 略*/

*  1
 *  2
 *  3
 *  4
 *  5
 *  6
 *  7
 *  8
 *  9
 *  10
 *  11
 *  12
 *  13
 *  14

[http://localhost:5680/zxmall/swagger-ui.html][http_localhost_5680_zxmall_swagger-ui.html]

![这里写图片描述][aHR0cDovL2ltZy5ibG9nLmNzZG4ubmV0LzIwMTcxMTI4MTUyNDA5NjIy]

</div>
 <link href="https://csdnimg.cn/release/phoenix/mdeditor/markdown_views-e44c3c0e64.css" rel="stylesheet">
 </div>

[Link 1]: http://creativecommons.org/licenses/by-sa/4.0/
[https_blog.csdn.net_xiaojin21cen_article_details_78654652]: https://blog.csdn.net/xiaojin21cen/article/details/78654652
[http_localhost_5680_zxmall_swagger-ui.html]: http://localhost:5680/zxmall/swagger-ui.html
[aHR0cDovL2ltZy5ibG9nLmNzZG4ubmV0LzIwMTcxMTI4MTUyNDA5NjIy]: https://imgconvert.csdnimg.cn/aHR0cDovL2ltZy5ibG9nLmNzZG4ubmV0LzIwMTcxMTI4MTUyNDA5NjIy