SpringBoot配置Swagger

一.描述

Swagger是一个规范的，标准的框架。用于生成、描述、调用和可视化Restful风格的Web服务。

二.使用

1.引入pom依赖：

<dependency>
      <groupId>io.springfox</groupId>
      <artifactId>springfox-swagger2</artifactId>
      <version>2.6.1</version>
</dependency>
<dependency>
     <groupId>io.springfox</groupId>
     <artifactId>springfox-swagger-ui</artifactId>
     <version>2.6.1</version>
</dependency>

2.创建Swagger的配置类：

package com.apps.swagger;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurationSupport;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.ParameterBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.schema.ModelRef;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Parameter;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

import java.util.ArrayList;
import java.util.List;

@Configuration
@EnableSwagger2
public class Swagger2 extends WebMvcConfigurationSupport {

    @Bean
    public Docket createRestApi() {
        ParameterBuilder tokenPar = new ParameterBuilder();
        List<Parameter> pars = new ArrayList<Parameter>();
        tokenPar.name("token").description("令牌").modelRef(new ModelRef("string")).parameterType("header").required(false).build();
        pars.add(tokenPar.build());
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.apps.controller"))
                .paths(PathSelectors.any())
                .build()
                .globalOperationParameters(pars)
                .apiInfo(apiInfo());
    }
    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("/**").addResourceLocations("classpath:/META-INF/resources/").setCachePeriod(0);
        //registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/").setCachePeriod(0);
    }
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("Sawgger2 API文档")
//                .description("，http://www.baidu.com")
//                .termsOfServiceUrl("http://www.baidu.com")
                .version("1.0")
                .build();
    }
    private class Invalid{

    }
}

如果接口中有和上面的添加的参数一样的名称的参数的话，是不会在swagger中显示出来的。

 三.Swagger的注解即其说明：

@ApiOperation:用在方法上，用于给方法增加说明

@Api:用在类上，说明该类的主要作用

@ApiModel: 用在实体类上，描述一个对象的信息

@ApiModelProperety: 用在实体类的属性中，描述一个model的属性

@ApiImplicitParams: 用在方法上，包含一组参数说明

@ApiImplicitParam: 给方法如参数增加说明

@ApiResponses：用于表示一组响应。

@ApiResponse：用在@ApiResponses中，一般用于表达一个错误的响应信息

​ l code：数字，例如400

​ l message：信息，例如"请求参数没填好"

​ l response：抛出异常的类

个人在开发中很少使用@ApiImplicitParam 作为参数的描述，这样描述在参数过多的条件下会有点麻烦。个人一般是将参数封装为一个完整对象（特别是GET方法），并利用@ApiModel注解去定义参数，如果不需要作为查询条件的，则加一个hidden = true，如果是必填属性，则增加一个required = true即可。

/**
 * @program: jpademo
 * @description: EmployeeController
 * @create 2018-10-23 11:07
 */
​
@RestController
@RequestMapping("emp")
@Api(value = "用户管理类")
public class EmployeeController {
​
 @Autowired
 private EmployeeReposiroty employeeReposiroty;
​
      /**
      * 增加人物
      * @param employee
      * @return
      */
     @PostMapping(value = "employee")
     @ApiOperation(value = "新增一个用户",notes = "新增之后返回对象")
     @ApiImplicitParam(paramType = "query",name = "employee",value = "用户",required = true)
     @ApiResponse(code = 400,message = "参数没有填好",response = String.class)
     public String insert(Employee employee){
         Employee employee1 = employeeReposiroty.save(employee);
         if(employee1 != null) {
             return SysNode.Judge.SUCCESS.getResult();
         }else {
             return SysNode.Judge.FAILD.getResult();
         }
     }
​
      /**
      * 删除单个用户
      * @param id
      * @return
      */
      @DeleteMapping(value = "employee/{id}")
      @ApiOperation(value = "删除用户",notes = "根据成员id删除单个用户")
      @ApiImplicitParam(paramType = "path",name = "id",value = "用户id",required = true,dataType = "Integer")
      @ApiResponse(code = 400,message = "参数没有填好",response = String.class)
      public String delete(@PathVariable("id")Integer id){
           try{
                employeeReposiroty.deleteById(id);
                return SysNode.Judge.SUCCESS.getResult();
           }catch (Exception e){
                e.printStackTrace();
               return SysNode.Judge.FAILD.getResult();
           }
      }
​
      /**
      * 修改单个成员
      * @param employee
      * @return
      */
      @PutMapping(value = "employee/{id}")
      @ApiOperation(value = "修改用户信息",notes = "根据成员id修改单个用户")
      public String update(Employee employee){
           /**
           * save方法如果参数属性缺失，会导致原本存在的数据为null
           */
           Employee employee1 = employeeReposiroty.saveAndFlush(employee);
           if (employee1 != null) {
                return SysNode.Judge.SUCCESS.getResult();
           }else {
               return SysNode.Judge.FAILD.getResult();
           }
      }
​
      /**
      * 获取所有成员,升序排列
      * @return
      */
      @GetMapping(value = "employee/sort")
      @ApiOperation(value = "查询全部用户",notes = "默认根据升序查询全部用户信息")
      public List<Employee> findAll(){
           Sort orders = new Sort(Sort.Direction.DESC,"employeeId");
           List<Employee> employeeList = employeeReposiroty.findAll(orders);
           return employeeList;
      }
​
      /**
     * 获取所有成员,升序排列
     * @return
      */
      @GetMapping(value = "employee/pageSort")
      @ApiOperation(value = "查询用户信息",notes = "查询用户信息")
      @ApiImplicitParams({
           @ApiImplicitParam(paramType = "query",name = "sort",value = "排序方式:asc|desc",dataType = "String",required = true),
           @ApiImplicitParam(paramType = "query",name = "pagenumber",value = "第几页",dataType = "Integer",required = true),
           @ApiImplicitParam(paramType = "query",name = "pageSize",value = "分页数",dataType = "Integer",required = true)
      })
      public List<Employee> findAllByPage(String sort,Integer pagenumber,Integer pageSize){
           try {
                Sort.Direction sortlast;
                if("desc".equals(sort.toLowerCase())){
                     sortlast = Sort.Direction.DESC;
               }else{          
                      sortlast = Sort.Direction.ASC;
               }
                     Sort orders = new Sort(sortlast, "employeeId");
                     Pageable pageable = new PageRequest(pagenumber, pageSize, orders);
​
                     Page<Employee> employeePage = employeeReposiroty.findAll(pageable);
                     List<Employee> employeeList = employeePage.getContent();
                     return employeeList;
           }catch (Exception e){
                e.printStackTrace();
                return null;
           }
      }
    /**
     * 自定义拓展jpa，根据用户名查找单个用户
     * @param username
     * @return
     */
     @GetMapping(value = "employee/find/{username}")
     @ApiOperation(value = "查询用户信息",notes = "根据用户登录名查询该用户信息")
     @ApiImplicitParam(paramType = "path",name = "username",value = "用户登录名",required = true,dataType = "String")
     public Employee findByUsername(@PathVariable("username") String username){
         List<Employee> employeeList = employeeReposiroty.findByUserNameOrderByEmployeeIdAsc(username);
         if (employeeList != null && !employeeList.isEmpty()){
             return employeeList.get(0);
         }
         return null;
     }
}

 

四.@ApiModel 接收对象传参

注意： 在后台采用对象接收参数时，Swagger自带的工具采用的是JSON传参， 测试时需要在参数上加入@RequestBody,正常运行采用form或URL提交时候请删除。

/**
 * @program: jpademo
 * @description: Employee
 * @create 2018-10-23 10:20
 */
​
@Data
@Entity
@Table(name = "employee")
@ApiModel(value = "用户对象模型")
public class Employee {
​
   @Id
   @GeneratedValue(strategy = GenerationType.IDENTITY)
   @Column(name = "employee_id")
   @Min(value = 1,groups = Employee.Children.class)
   private Integer employeeId;
​
   @Column(name = "user_name",length = 20,nullable = true)
   @ApiModelProperty(value = "userName",required = true)
   private String userName;
​
   @Column(nullable = true)
   @Size(min = 0,max = 65,message = "年龄超过范围限制",groups = Employee.Audit.class)
   @ApiModelProperty(value = "age",required = true)
   private Integer age;
​
   @Column(name="gra_id")
   @ApiModelProperty(value = "graId",required = true)
   //@Digits(integer = 12,fraction = 4)  //限制必须为一个小数，且整数部分的 位数 不能超过integer，小数部分的 位数 不能超过fraction
   private Integer graId;
​
   public interface Audit{};
​
   public interface Children{};
​
}

文章部分转载自：https://www.jianshu.com/p/a0caf58b3653