如何使用swagger（一）

Swagger使用

1、描述

Swagger 是一個規范和完整的框架，用於生成、描述、調用和可視化 RESTful 風格的 Web 服務。

作用：

1.接口的文檔在線自動生成。

2.功能測試。

2、運用

a) maven導入Swagger

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

b) 創建Swagger2配置類

/**
 * @program: jpademo
 * @description: Swagger
 * @author: ZengGuangfu
 * @create 2018-10-24 10:12
 */
​
@Configuration
@EnableSwagger2
public class Swagger {
​
   @Bean
   public Docket docket(){
       return new Docket(DocumentationType.SWAGGER_2)
         .apiInfo(apiInfo())
         .select()
         .apis(RequestHandlerSelectors.basePackage("com.example.springbootjpa.jpademo.controller"))
         .paths(PathSelectors.any())
         .build();
   }
​
   public ApiInfo apiInfo(){
       return new ApiInfoBuilder()
         .title("利用swagger2構建的API文檔")
         .description("用restful風格寫接口")
         .termsOfServiceUrl("")
         .version("1.0")
         .build();
   }
}

如上所示，docket() 方法創建Docket的Bean對象，apiInfo()則是創建ApiInfo的基本信息。

鏈式方法解析：

3、注解及其說明

@Api : 用在類上，說明該類的主要作用。

@ApiOperation：用在方法上，給API增加方法說明。

@ApiImplicitParams : 用在方法上，包含一組參數說明。

@ApiImplicitParam：用來注解來給方法入參增加說明。

 

 

@ApiResponses：用於表示一組響應。

@ApiResponse：用在@ApiResponses中，一般用於表達一個錯誤的響應信息

​ l code：數字，例如400

​ l message：信息，例如"請求參數沒填好"

​ l response：拋出異常的類

@ApiModel：用在返回對象類上，描述一個Model的信息（一般用在請求參數無法使用@ApiImplicitParam注解進行描述的時候）

​ l @ApiModelProperty：描述一個model的屬性

以下僅僅是一個例子，其實我個人在開發中很少使用@ApiImplicitParam 作為參數的描述，這樣描述在參數過多的條件下會有點麻煩。個人一般是將參數封裝為一個完整對象（特別是GET方法），並利用@ApiModel注解去定義參數，如果不需要作為查詢條件的，則加一個hidden = true，如果是必填屬性，則增加一個required = true即可。

例子：

/**
 * @program: jpademo
 * @description: EmployeeController
 * @author: ZengGuangfu
 * @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;
     }
​
     /**
     * 測試用
     * @return
     */
     @GetMapping(value = "employee/grade")
     public List<Object[]> findEmployeeAndGrade(){
         Pageable pageable = new PageRequest(0,3);
​
         Page<Object[]> page = employeeReposiroty.findEmployeeAndGrade(pageable);
         System.out.println(page.getTotalElements()+"----------結果總數------------");
         System.out.println(page.getTotalPages()+"--------根據pageSize的總頁數-----------");
         System.out.println(page.getNumber()+"--------當前頁數，pageNumber----------");
         System.out.println(page.getNumberOfElements()+"--------當前頁有幾個數據--------");
         System.out.println(page.getSize()+"---------PageSize-------------");
         System.out.println(page.getSort()+"---------排序方式，沒有則是'UNSORTED'----------");
​
         List<Object[]> objects = page.getContent();
         return objects;
    }
}

4、測試登錄 localhost:8080/swagger-ui.html

 

 API 操作測試，修改

 

 

 

 

5、@ApiModel 接收對象傳參

注意： 在后台采用對象接收參數時，Swagger自帶的工具采用的是JSON傳參， 測試時需要在參數上加入@RequestBody,正常運行采用form或URL提交時候請刪除。

例子：

/**
 * @program: jpademo
 * @description: Employee
 * @author: ZengGuangfu
 * @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{};
​
}