Swagger常用参数用法

别提示：本人博客部分有参考网络其他博客，但均是本人亲手编写过并验证通过。如发现博客有错误，请及时提出以免误导其他人，谢谢！欢迎转载，但记得标明文章出处：http://www.cnblogs.com/mao2080/

1、常用参数

a、配置参数

 package com.mao.swagger.config;

 import org.springframework.context.annotation.Bean;
 import org.springframework.context.annotation.Configuration;

 import springfox.documentation.builders.PathSelectors;
 import springfox.documentation.builders.RequestHandlerSelectors;
 import springfox.documentation.spi.DocumentationType;
 import springfox.documentation.spring.web.plugins.Docket;
 import springfox.documentation.swagger2.annotations.EnableSwagger2;

 @Configuration
 @EnableSwagger2
 public class SwaggerConfig {

     @Bean
     public Docket userDocket() {
         return new Docket(DocumentationType.SWAGGER_2)
                 .groupName("商品接口文档")
                 .select()
                 .paths(PathSelectors.any())
                 .apis(RequestHandlerSelectors.basePackage("com.mao.swagger.goods.controller"))
                 .build();
     }

     @Bean
     public Docket deviceDocket() {
         return new Docket(DocumentationType.SWAGGER_2)
                 .groupName("用户接口文档")
                 .select()
                 .paths(PathSelectors.any())
                 .apis(RequestHandlerSelectors.basePackage("com.mao.swagger.user.controller"))
                 .build();
     }

 }

• .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

 package com.mao.swagger.user.controller;

 import org.springframework.http.HttpStatus;
 import org.springframework.http.MediaType;
 import org.springframework.web.bind.annotation.RequestBody;
 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 com.mao.swagger.beans.ResObject;
 import com.mao.swagger.beans.User;

 import io.swagger.annotations.Api;
 import io.swagger.annotations.ApiImplicitParam;
 import io.swagger.annotations.ApiImplicitParams;
 import io.swagger.annotations.ApiOperation;
 import springfox.documentation.annotations.ApiIgnore;

 /**
  * Hello world!
  *
  */
 @Api(description = "用户接口")
 @RestController
 @RequestMapping("/userController")
 public class UserController {

     @ApiOperation(value = "新增用户" ,  notes="新增注册")
     @RequestMapping(value="/createUser",method=RequestMethod.POST,consumes= MediaType.APPLICATION_JSON_VALUE)
     public ResObject createUser(@RequestBody User user){
         System.out.println("createUser:::"+user.toString());
         return new ResObject(HttpStatus.OK.value(), "新增成功.");
     }

     @ApiOperation(value = "修改用户" ,  notes="修改用户")
     @RequestMapping(value="/updateUser",method=RequestMethod.POST,consumes= MediaType.APPLICATION_JSON_VALUE)
     public ResObject updateUser(@RequestBody User user){
         System.out.println("updateUser:::"+user.toString());
         return new ResObject(HttpStatus.OK.value(), "修改成功.");
     }

     @ApiOperation(value = "删除用户" ,  notes="删除用户")
     @ApiImplicitParams({
         @ApiImplicitParam(name = "userId", value = "用户标识", required = true, paramType = "query", dataType = "String")
     })
     @RequestMapping(value="/deleteUser",method=RequestMethod.DELETE)
     public ResObject deleteUser(@RequestParam("userId") String userId){
         System.out.println("deleteUser:::"+userId);
         return new ResObject(HttpStatus.OK.value(), "删除成功.");
     }

     @ApiOperation(value = "查询用户" ,  notes="查询用户")
     @ApiImplicitParam(name = "userId", value = "用户标识", required = true, paramType = "query", dataType = "String")
     @RequestMapping(value="/queryUser",method=RequestMethod.GET)
     public ResObject queryUser(@RequestParam("userId") String userId){
         System.out.println("queryUser:::"+userId);
         User user = new User(userId, "张三", "******", "mao2080@sina.com");
         return new ResObject(HttpStatus.OK.value(), user);
     }

     @ApiOperation(value = "被遗忘的方法" ,  notes="这个方法将被不会显示")
     @ApiIgnore
     @ApiImplicitParam(name = "userId", value = "用户标识", required = true, paramType = "query", dataType = "String")
     @RequestMapping(value="/queryUser1",method=RequestMethod.GET)
     public ResObject queryUser1(@RequestParam("userId") String userId){
         System.out.println("queryUser:::"+userId);
         User user = new User(userId, "张三", "******", "mao2080@sina.com");
         return new ResObject(HttpStatus.OK.value(), user);
     }

 }

效果图1

code2

 package com.mao.swagger.beans;

 import io.swagger.annotations.ApiModel;
 import io.swagger.annotations.ApiModelProperty;

 @ApiModel(value="user", description="用户对象")
 public class User {

     @ApiModelProperty(value="用户id",name="userId",example="001")
     private String userId;

     @ApiModelProperty(value="用户名",name="userName",example="mao2080")
     private String userName;

     @ApiModelProperty(value="密码",name="password",example="123456")
     private String password;

     @ApiModelProperty(value="邮箱",name="email",example="mao2080@sina.com")
     private String email;

     public User() {
         super();
     }

     public User(String userId, String userName, String password, String email) {
         super();
         this.userId = userId;
         this.userName = userName;
         this.password = password;
         this.email = email;
     }

     public String getUserId() {
         return userId;
     }

     public void setUserId(String userId) {
         this.userId = userId;
     }

     public String getUserName() {
         return userName;
     }

     public void setUserName(String userName) {
         this.userName = userName;
     }

     public String getPassword() {
         return password;
     }

     public void setPassword(String password) {
         this.password = password;
     }

     public String getEmail() {
         return email;
     }

     public void setEmail(String email) {
         this.email = email;
     }

     @Override
     public String toString() {
         return "User [userId=" + userId + ", userName=" + userName + ", password=" + password + ", email=" + email+"]";
     }
69
 }

效果图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操作步骤