Swagger常用參數用法
阿新 • • 發佈：2018-05-10
order int dia www context 多個 sele doc amp
別提示：本人博客部分有參考網絡其他博客，但均是本人親手編寫過並驗證通過。如發現博客有錯誤，請及時提出以免誤導其他人，謝謝！歡迎轉載，但記得標明文章出處：http://www.cnblogs.com/mao2080/
1、常用參數
a、配置參數
1 package com.mao.swagger.config; 2 3 import org.springframework.context.annotation.Bean; 4 import org.springframework.context.annotation.Configuration; 5 6 import springfox.documentation.builders.PathSelectors;7 import springfox.documentation.builders.RequestHandlerSelectors; 8 import springfox.documentation.spi.DocumentationType; 9 import springfox.documentation.spring.web.plugins.Docket; 10 import springfox.documentation.swagger2.annotations.EnableSwagger2; 11 12 @Configuration 13 @EnableSwagger2 14 publicclass SwaggerConfig { 15 16 @Bean 17 public Docket userDocket() { 18 return new Docket(DocumentationType.SWAGGER_2) 19 .groupName("商品接口文檔") 20 .select() 21 .paths(PathSelectors.any()) 22 .apis(RequestHandlerSelectors.basePackage("com.mao.swagger.goods.controller"))23 .build(); 24 } 25 26 @Bean 27 public Docket deviceDocket() { 28 return new Docket(DocumentationType.SWAGGER_2) 29 .groupName("用戶接口文檔") 30 .select() 31 .paths(PathSelectors.any()) 32 .apis(RequestHandlerSelectors.basePackage("com.mao.swagger.user.controller")) 33 .build(); 34 } 35 36 }
- .groupName("商品接口文檔") 設置欄目名
- .select() 初始化並返回一個API選擇構造器
- .paths(PathSelectors.any()) 設置路徑篩選
- .apis(RequestHandlerSelectors.basePackage("com.mao.swagger.goods.controller")) 添加路徑選擇條件
- .build();
PathSelectors類的方法：
Predicate<String> any():滿足條件的路徑，該斷言總為true
Predicate<String> none():不滿足條件的路徑,該斷言總為false (生產環境可以屏蔽掉swagger：https://blog.csdn.net/goldenfish1919/article/details/78280051)
Predicate<String> regex(final String pathRegex):符合正則的路徑
RequestHandlerSelectors類的方法：
Predicate<RequestHandler> any()：返回包含所有滿足條件的請求處理器的斷言，該斷言總為true
Predicate<RequestHandler> none()：返回不滿足條件的請求處理器的斷言,該斷言總為false
Predicate<RequestHandler> basePackage(final String basePackage)：返回一個斷言(Predicate)，該斷言包含所有匹配basePackage下所有類的請求路徑的請求處理器
b、接口參數
- @Api()用於類； 表示標識這個類是swagger的資源 【參考code1，效果圖1】
- @ApiOperation()用於方法； 表示一個http請求的操作 【參考code1，效果圖1】
- @ApiParam()用於方法，參數，字段說明； 表示對參數的添加元數據（說明或是否必填等） 【暫時沒用，當前使用SpringMVC@RequestParam】
- @ApiModel()用於類 表示對類進行說明，用於參數用實體類接收 【參考code2，效果圖2，3】
- @ApiModelProperty()用於方法，字段 表示對model屬性的說明或者數據操作更改 【參考code2，效果圖2，3】
- @ApiIgnore()用於類，方法，方法參數 表示這個方法或者類被忽略 【參考code1，效果圖1】
- @ApiImplicitParam() 用於方法 表示單獨的請求參數 【參考code1，效果圖1】
- @ApiImplicitParams() 用於方法，包含多個 @ApiImplicitParam 【參考code1，效果圖1】
code1
1 package com.mao.swagger.user.controller; 2 3 import org.springframework.http.HttpStatus; 4 import org.springframework.http.MediaType; 5 import org.springframework.web.bind.annotation.RequestBody; 6 import org.springframework.web.bind.annotation.RequestMapping; 7 import org.springframework.web.bind.annotation.RequestMethod; 8 import org.springframework.web.bind.annotation.RequestParam; 9 import org.springframework.web.bind.annotation.RestController; 10 11 import com.mao.swagger.beans.ResObject; 12 import com.mao.swagger.beans.User; 13 14 import io.swagger.annotations.Api; 15 import io.swagger.annotations.ApiImplicitParam; 16 import io.swagger.annotations.ApiImplicitParams; 17 import io.swagger.annotations.ApiOperation; 18 import springfox.documentation.annotations.ApiIgnore; 19 20 /** 21 * Hello world! 22 * 23 */ 24 @Api(description = "用戶接口") 25 @RestController 26 @RequestMapping("/userController") 27 public class UserController { 28 29 @ApiOperation(value = "新增用戶" , notes="新增註冊") 30 @RequestMapping(value="/createUser",method=RequestMethod.POST,consumes= MediaType.APPLICATION_JSON_VALUE) 31 public ResObject createUser(@RequestBody User user){ 32 System.out.println("createUser:::"+user.toString()); 33 return new ResObject(HttpStatus.OK.value(), "新增成功."); 34 } 35 36 @ApiOperation(value = "修改用戶" , notes="修改用戶") 37 @RequestMapping(value="/updateUser",method=RequestMethod.POST,consumes= MediaType.APPLICATION_JSON_VALUE) 38 public ResObject updateUser(@RequestBody User user){ 39 System.out.println("updateUser:::"+user.toString()); 40 return new ResObject(HttpStatus.OK.value(), "修改成功."); 41 } 42 43 @ApiOperation(value = "刪除用戶" , notes="刪除用戶") 44 @ApiImplicitParams({ 45 @ApiImplicitParam(name = "userId", value = "用戶標識", required = true, paramType = "query", dataType = "String") 46 }) 47 @RequestMapping(value="/deleteUser",method=RequestMethod.DELETE) 48 public ResObject deleteUser(@RequestParam("userId") String userId){ 49 System.out.println("deleteUser:::"+userId); 50 return new ResObject(HttpStatus.OK.value(), "刪除成功."); 51 } 52 53 @ApiOperation(value = "查詢用戶" , notes="查詢用戶") 54 @ApiImplicitParam(name = "userId", value = "用戶標識", required = true, paramType = "query", dataType = "String") 55 @RequestMapping(value="/queryUser",method=RequestMethod.GET) 56 public ResObject queryUser(@RequestParam("userId") String userId){ 57 System.out.println("queryUser:::"+userId); 58 User user = new User(userId, "張三", "******", "[email protected]"); 59 return new ResObject(HttpStatus.OK.value(), user); 60 } 61 62 @ApiOperation(value = "這個方法獎杯忽略" , notes="不會顯示") 63 @ApiIgnore 64 @ApiImplicitParam(name = "userId", value = "用戶標識", required = true, paramType = "query", dataType = "String") 65 @RequestMapping(value="/queryUser1",method=RequestMethod.GET) 66 public ResObject queryUser1(@RequestParam("userId") String userId){ 67 System.out.println("queryUser:::"+userId); 68 User user = new User(userId, "張三", "******", "[email protected]"); 69 return new ResObject(HttpStatus.OK.value(), user); 70 } 71 72 }
效果圖1
code2
1 package com.mao.swagger.beans; 2 3 import io.swagger.annotations.ApiModel; 4 import io.swagger.annotations.ApiModelProperty; 5 6 @ApiModel(value="user", description="用戶對象") 7 public class User { 8 9 @ApiModelProperty(value="用戶id",name="userId",example="001") 10 private String userId; 11 12 @ApiModelProperty(value="用戶名",name="userName",example="mao2080") 13 private String userName; 14 15 @ApiModelProperty(value="密碼",name="password",example="123456") 16 private String password; 17 18 @ApiModelProperty(value="郵箱",name="email",example="[email protected]") 19 private String email; 20 21 public User() { 22 super(); 23 } 24 25 public User(String userId, String userName, String password, String email) { 26 super(); 27 this.userId = userId; 28 this.userName = userName; 29 this.password = password; 30 this.email = email; 31 } 32 33 public String getUserId() { 34 return userId; 35 } 36 37 public void setUserId(String userId) { 38 this.userId = userId; 39 } 40 41 public String getUserName() { 42 return userName; 43 } 44 45 public void setUserName(String userName) { 46 this.userName = userName; 47 } 48 49 public String getPassword() { 50 return password; 51 } 52 53 public void setPassword(String password) { 54 this.password = password; 55 } 56 57 public String getEmail() { 58 return email; 59 } 60 61 public void setEmail(String email) { 62 this.email = email; 63 } 64 65 @Override 66 public String toString() { 67 return "User [userId=" + userId + ", userName=" + userName + ", password=" + password + ", email=" + email 68 + "]"; 69 } 70 71 }
效果圖2
效果圖3
2、參考網站
https://blog.csdn.net/z28126308/article/details/71126677
https://blog.csdn.net/u014231523/article/details/76522486
https://www.cnblogs.com/softidea/p/6251249.html
3、推廣閱讀
Springboot集成Swagger操作步驟
Swagger常用參數用法