| |
Controller 相关注解 @Api: 可设置对控制器的描述。 表 1. @Api 主要属性
| 注解属性 |
类型 |
描述 |
| tags |
String[] |
控制器标签。 |
| description |
String |
控制器描述（该字段被申明为过期）。 |
接口相关注解
| 注解属性 |
类型 |
描述 |
| value |
String |
接口说明。 |
| notes |
String |
接口发布说明。 |
| tags |
Stirng[] |
标签。 |
| response |
Class<?> |
接口返回类型。 |
| httpMethod |
String |
接口请求方式。 |
| 注解属性 |
描述 |
| paramType |
查询参数类型，实际上就是参数放在那里。取值：
- path：以地址的形式提交数据，根据 id 查询用户的接口就是这种形式传参。
- query：Query string 的方式传参。
- header：以流的形式提交。
- form：以 Form 表单的形式提交。
|
| dataType |
参数的数据类型。取值：
|
| name |
参数名字。 |
| value |
参数意义的描述。 |
| required |
是否必填。取值：
|
Model 相关注解
| 注解属性 |
类型 |
描述 |
| value |
String |
字段说明。 |
| name |
String |
重写字段名称。 |
| dataType |
Stirng |
重写字段类型。 |
| required |
boolean |
是否必填。 |
| example |
Stirng |
举例说明。 |
| hidden |
boolean |
是否在文档中隐藏该字段。 |
| allowEmptyValue |
boolean |
是否允许为空。 |
| allowableValues |
String |
该字段允许的值，当我们 API 的某个参数为枚举类型时，使用这个属性就可以清楚地告诉 API 使用者该参数所能允许传入的值。 |
- @ApiModel: 可设置接口相关实体的描述。
- @ApiModelProperty: 可设置实体属性的相关描述。
表 4. @ApiModelProperty 主要属性
- @ApiIgnore: Swagger 文档不会显示拥有该注解的接口。
- @ApiImplicitParams: 用于描述接口的非对象参数集。
- @ApiImplicitParam: 用于描述接口的非对象参数，一般与 @ApiImplicitParams 组合使用。
表 3. @ApiImplicitParam 主要属性
- @ApiOperation: 可设置对接口的描述。
表 2. @ApiOperation 主要属性
|
|
1、swagger2 注解整体说明 用于controller类上：
用于方法上面（说明参数的含义）：
| 注解 |
说明 |
| @ApiOperation |
方法的说明 |
| @ApiImplicitParams、@ApiImplicitParam |
方法的参数的说明；@ApiImplicitParams 用于指定单个参数的说明 |
用于方法上面（返回参数或对象的说明）：
| 注解 |
说明 |
| @ApiResponses、@ApiResponse |
方法返回值的说明 ；@ApiResponses 用于指定单个参数的说明 |
对象类：
| 注解 |
说明 |
| @ApiModel |
用在JavaBean类上，说明JavaBean的 用途 |
| @ApiModelProperty |
用在JavaBean类的属性上面，说明此属性的的含议 |
2、@Api：请求类的说明
| @Api：放在 请求的类上，与 @Controller 并列，说明类的作用，如用户模块，订单类等。 tags="说明该类的作用" value="该参数没什么意义，所以不需要配置" |
示例：
| @Api(tags="订单模块") @Controller public class OrderController { } |
@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="方法的备注说明" |
3.1、@ApiImplicitParams、@ApiImplicitParam：方法参数的说明
| @ApiImplicitParams：用在请求的方法上，包含一组参数说明 @ApiImplicitParam：对单个参数的说明 name：参数名 value：参数的说明、描述 required：参数是否必须必填 paramType：参数放在哪个地方 · query --> 请求参数的获取：@RequestParam · header --> 请求参数的获取：@RequestHeader · path（用于restful接口）--> 请求参数的获取：@PathVariable · body（请求体）--> @RequestBody User user · form（普通表单提交） dataType：参数类型，默认String，其它值dataType="Integer" defaultValue：参数的默认值 |
示列：
| @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); } |
4、@ApiResponses、@ApiResponse：方法返回值的状态码说明
| @ApiResponses：方法返回对象的说明 @ApiResponse：每个参数的说明 code：数字，例如400 message：信息，例如"请求参数没填好" response：抛出异常的类 |
示例：
| @Api(tags="用户模块") @Controller public class UserController { @ApiOperation("获取用户信息") @ApiImplicitParams({ @ApiImplicitParam(paramType="query", name="userId", dataType="String", required=true, value="用户Id") }) @ApiResponses({ @ApiResponse(code = 200, message = "请求成功"), @ApiResponse(code = 400, message = "请求参数没填好"), @ApiResponse(code = 404, message = "请求路径没有或页面跳转路径不对") }) @ResponseBody @RequestMapping("/list") public JsonResult list(@RequestParam String userId) { ... return JsonResult.ok().put("page", pageUtil); } } |
5、@ApiModel：用于JavaBean上面，表示对JavaBean 的功能描述 @ApiModel的用途有2个：
- 当请求数据描述，即 @RequestBody 时， 用于封装请求（包括数据的各种校验）数据；
- 当响应值是对象时，即 @ResponseBody 时，用于返回值对象的描述。
5.1、当请求数据描述时， @RequestBody 时的使用
| @ApiModel(description = "用户登录") public class UserLoginVO implements Serializable { private static final long serialVersionUID = 1L; @ApiModelProperty(value = "用户名",required=true) private String username; @ApiModelProperty(value = "密码",required=true) private String password; // getter/setter省略 } |
| @Api(tags="用户模块") @Controller public class UserController { @ApiOperation(value = "用户登录", notes = "") @PostMapping(value = "/login") public R login(@RequestBody UserLoginVO userLoginVO) { User user=userSerivce.login(userLoginVO); return R.okData(user); } } |
5.2、@ApiModelProperty：用在JavaBean类的属性上面，说明属性的含义 示例:
| @ApiModel(description= "返回响应数据") public class RestMessage implements Serializable{ @ApiModelProperty(value = "是否成功",required=true) private boolean success=true; @ApiModelProperty(value = "错误码") private Integer errCode; @ApiModelProperty(value = "提示信息") private String message; @ApiModelProperty(value = "数据") private Object data; /* getter/setter 略*/ } |
|