如何使用@ApiImplicitParams、ApiImplicitParam

這篇文章主要講解了“如何使用@ApiImplicitParams、ApiImplicitParam”，文中的講解內(nèi)容簡單清晰，易于學(xué)習(xí)與理解，下面請大家跟著小編的思路慢慢深入，一起來研究和學(xué)習(xí)“如何使用@ApiImplicitParams、ApiImplicitParam”吧！

目錄

• @ApiImplicitParam

• 參數(shù)

• 類型 作用

• @ApiImplicitParams

• paramType 示例詳解

• 小結(jié)一下

• 測試

@ApiImplicitParam

作用在方法上，表示單獨的請求參數(shù)

參數(shù)

• name：參數(shù)名。

• value：參數(shù)的具體意義，作用。

• required：參數(shù)是否必填。

• dataType：參數(shù)的數(shù)據(jù)類型。

• paramType：查詢參數(shù)類型，這里有幾種形式：

類型 作用

• path 以地址的形式提交數(shù)據(jù)

• query 直接跟參數(shù)完成自動映射賦值

• body 以流的形式提交 僅支持POST

• header 參數(shù)在request headers 里邊提交

• form 以form表單的形式提交 僅支持POST

在這里我被坑過一次：當(dāng)我發(fā)POST請求的時候，當(dāng)時接受的整個參數(shù)，不論我用body還是query，后臺都會報Body Missing錯誤。

這個參數(shù)和SpringMvc中的@RequestBody沖突，索性我就去掉了paramType，對接口測試并沒有影響。

@ApiImplicitParams

用于方法，包含多個 @ApiImplicitParam：

例：

@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

@RequestMapping(value = "/findById1/{id}", method = RequestMethod.GET, produces = MediaType.APPLICATION_JSON_UTF8_VALUE)
@PathVariable(name = "id") Long id

body

@ApiImplicitParams({ @ApiImplicitParam(paramType = "body", dataType = "MessageParam", name = "param", value = "信息參數(shù)", required = true) })
@RequestMapping(value = "/findById3", method = RequestMethod.POST, produces = MediaType.APPLICATION_JSON_UTF8_VALUE, consumes = MediaType.APPLICATION_JSON_VALUE)
@RequestBody MessageParam param

提交的參數(shù)是這個對象的一個json，然后會自動解析到對應(yīng)的字段上去，也可以通過流的形式接收當(dāng)前的請求數(shù)據(jù)，但是這個和上面的接收方式僅能使用一個（用@RequestBody之后流就會關(guān)閉了）

header

@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

@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)

小結(jié)一下

(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：用在方法上包含一組參數(shù)說明

• @ApiImplicitParam：用在@ApiImplicitParams注解中，指定一個請求參數(shù)的各個方面

• paramType：參數(shù)放在哪個地方

• header-->請求參數(shù)的獲?。篅RequestHeader

• query-->請求參數(shù)的獲取：@RequestParam

• path（用于restful接口）-->請求參數(shù)的獲?。篅PathVariable

• body（不常用）

• form（不常用）

• name：參數(shù)名

• dataType：參數(shù)類型

• required：參數(shù)是否必須傳

• value：參數(shù)的意思

• defaultValue：參數(shù)的默認(rèn)值

• @ApiResponses：用于表示一組響應(yīng)

• @ApiResponse：用在@ApiResponses中，一般用于表達(dá)一個錯誤的響應(yīng)信息

• code：數(shù)字，例如400

• message：信息，例如"請求參數(shù)沒填好"

• response：拋出異常的類

• 以上這些就是最常用的幾個注解了。

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相關(guān)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="請求參數(shù)沒填好"),
@ApiResponse(code=404,message="請求路徑?jīng)]有或頁面跳轉(zhuǎn)路徑不對")
})
@RequestMapping(value="/getUser",method=RequestMethod.GET)
public User getUser(@RequestHeader("username") String username, @RequestParam("password") String password) {
return userService.getUser(username,password);
}
}

測試

啟動服務(wù)，瀏覽器輸入"http://localhost:8080/swagger-ui.html"

在上面案例中我們可以知道如果在request域中我們使用reques.getHeader()和使用@RequestHeader注解作用是一樣的，其它內(nèi)容類似。

• @ApiResponses：用于表示一組響應(yīng)

• @ApiResponse：用在@ApiResponses中，一般用于表達(dá)一個錯誤的響應(yīng)信息

• code：數(shù)字，例如400

• message：信息，例如”請求參數(shù)沒填好”

• response：拋出異常的類

@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="請求參數(shù)沒填好"),
@ApiResponse(code=404,message="請求路徑?jīng)]有或頁面跳轉(zhuǎn)路徑不對")
})
@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);
}

感謝各位的閱讀，以上就是“如何使用@ApiImplicitParams、ApiImplicitParam”的內(nèi)容了，經(jīng)過本文的學(xué)習(xí)后，相信大家對如何使用@ApiImplicitParams、ApiImplicitParam這一問題有了更深刻的體會，具體使用情況還需要大家實踐驗證。這里是億速云，小編將為大家推送更多相關(guān)知識點的文章，歡迎關(guān)注！