@ApiImplicitParam
作用在方法上,表示单独的请求参数
参数
-
name
:参数名。 -
value
:参数的具体意义,作用。 -
required
:参数是否必填。 -
dataType
:参数的数据类型。 -
paramType
:查询参数类型,这里有几种形式:
类型 作用
-
path
以地址的形式提交数据 -
query
直接跟参数完成自动映射赋值 -
body
以流的形式提交 仅支持POST -
header
参数在request headers 里边提交 -
form
以form表单的形式提交 仅支持POST
在这里我被坑过一次:当我发POST请求的时候,当时接受的整个参数,不论我用body还是query,后台都会报Body Missing错误。
这个参数和SpringMvc中的@RequestBody冲突,索性我就去掉了paramType,对接口测试并没有影响。
@ApiImplicitParams
用于方法,包含多个 @ApiImplicitParam:
例:
1
2
3
4
5
6
7
8
|
@ApiOperation ( "查询测试" )
@GetMapping ( "select" )
//@ApiImplicitParam(name="name",value="用户名",dataType="String", paramType = "query")
@ApiImplicitParams ({
@ApiImplicitParam (name= "name" ,value= "用户名" ,dataType= "string" , paramType = "query" ,example= "xingguo" ),
@ApiImplicitParam (name= "id" ,value= "用户id" ,dataType= "long" , paramType = "query" )})
public void select(){
}
|
paramType 示例详解
path
1
2
|
@RequestMapping (value = "/findById1/{id}" , method = RequestMethod.GET, produces = MediaType.APPLICATION_JSON_UTF8_VALUE)
@PathVariable (name = "id" ) Long id
|
body
1
2
3
|
@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之后流就会关闭了)
header
1
2
3
4
5
|
@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
1
2
|
@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)
|
小结一下
(1)对于@ApiImplicitParam的paramType:query、form域中的值需要使用@RequestParam获取, header域中的值需要使用@RequestHeader来获取,path域中的值需要使用@PathVariable来获取,body域中的值使用@RequestBody来获取,否则可能出错;而且如果paramType是body,name就不能是body,否则有问题,与官方文档中的“If paramType is "body", the name should be "body"不符。
-
@ApiImplicitParams
:用在方法上包含一组参数说明 -
@ApiImplicitParam
:用在@ApiImplicitParams注解中,指定一个请求参数的各个方面 -
paramType
:参数放在哪个地方 -
header
-->请求参数的获取:@RequestHeader -
query
-->请求参数的获取:@RequestParam -
path
(用于restful接口)-->请求参数的获取:@PathVariable -
body
(不常用) -
form
(不常用) -
name
:参数名 -
dataType
:参数类型 -
required
:参数是否必须传 -
value
:参数的意思 -
defaultValue
:参数的默认值 -
@ApiResponses
:用于表示一组响应 -
@ApiResponse
:用在@ApiResponses中,一般用于表达一个错误的响应信息 -
code
:数字,例如400 -
message
:信息,例如"请求参数没填好" -
response
:抛出异常的类 - 以上这些就是最常用的几个注解了。
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
|
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.RequestHeader;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestMethod;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiImplicitParams;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiResponse;
import io.swagger.annotations.ApiResponses;
@RestController
@RequestMapping ( "/user" )
@Api ( "userController相关api" )
public class UserController {
@Autowired
private UserService userService;
@ApiOperation ( "获取用户信息" )
@ApiImplicitParams ({
@ApiImplicitParam (paramType= "header" ,name= "username" ,dataType= "String" ,required= true ,value= "用户的姓名" ,defaultValue= "zhaojigang" ),
@ApiImplicitParam (paramType= "query" ,name= "password" ,dataType= "String" ,required= true ,value= "用户的密码" ,defaultValue= "wangna" )
})
@ApiResponses ({
@ApiResponse (code= 400 ,message= "请求参数没填好" ),
@ApiResponse (code= 404 ,message= "请求路径没有或页面跳转路径不对" )
})
@RequestMapping (value= "/getUser" ,method=RequestMethod.GET)
public User getUser( @RequestHeader ( "username" ) String username, @RequestParam ( "password" ) String password) {
return userService.getUser(username,password);
}
}
|
测试
启动服务,浏览器输入"http://localhost:8080/swagger-ui.html"
在上面案例中我们可以知道如果在request域中我们使用reques.getHeader()和使用@RequestHeader注解作用是一样的,其它内容类似。
-
@ApiResponses
:用于表示一组响应 -
@ApiResponse
:用在@ApiResponses中,一般用于表达一个错误的响应信息 -
code
:数字,例如400 -
message
:信息,例如”请求参数没填好” -
response
:抛出异常的类
1
2
3
4
5
6
7
8
9
10
11
12
13
|
@ApiOperation ( "获取用户信息" )
@ApiImplicitParams ({ @ApiImplicitParam (paramType= "header" ,name= "name" ,dataType= "String" ,required= true ,value= "用户的姓名" ,defaultValue= "zhaojigang" ),
@ApiImplicitParam (paramType= "query" ,name= "pwd" ,dataType= "String" ,required= true ,value= "用户的密码" ,defaultValue= "wangna" )
})
@ApiResponses ({ @ApiResponse (code= 400 ,message= "请求参数没填好" ),
@ApiResponse (code= 404 ,message= "请求路径没有或页面跳转路径不对" )
})
@RequestMapping (value= "/getUser" ,method= RequestMethod.GET)
public User getUser( @RequestHeader ( "name" ) String name, @RequestParam ( "pwd" ) String pwd) {
System.out.println(name);
System.out.println(pwd);
return userRepository.getUserByNameAndPwd(name,pwd);
}
|
以上为个人经验,希望能给大家一个参考,也希望大家多多支持服务器之家。
原文链接:https://www.cnblogs.com/h-c-g/p/11004020.html