Swagger常用参数用法
Posted 知行合一
tags:
篇首语:本文由小常识网(cha138.com)小编为大家整理,主要介绍了Swagger常用参数用法相关的知识,希望对你有一定的参考价值。
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 public class 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, "张三", "******", "mao2080@sina.com"); 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, "张三", "******", "mao2080@sina.com"); 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="mao2080@sina.com") 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 }
效果图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、推广阅读
以上是关于Swagger常用参数用法的主要内容,如果未能解决你的问题,请参考以下文章