swagger 測試插件的學習筆記

why

現在的開發開始傾向於前後端分離的方式，而前後端分離必然會有API文檔來爲前後端提供一個交互的橋樑。傳統的word文檔不僅編寫麻煩，後期的版本維護也是一大問題。

waht

Swagger就能滿足我們對維護和測試API文檔提供用戶友好的UI界面， 現在Swagger已被Spring集成，更加方便我們在spring項目中使用。
Swagger說明鏈接
這裏就不給發官方網址了，但想要更準確的瞭解swagger還是去官網更好

how

1. 添加swagger依賴

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

2. swagger的配置
   Swagger2.java 源碼文件要放在Application.java 同一包下

package com.demo.swagger;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

/**
 * Swagger2 培養類
 * 在與spring boot集成時，放在Application.java文件同包下
 * @Configuration 用於啓動這個類地配置
 * @EnableSwagger2 用來啓動Swagger2
 */
@Configuration
@EnableSwagger2
public class Swagger2 {

    /**
     * 創建api應用
     * apiInfo（）增加API相關信息
     * 通過select函數返回一個ApiSelectorBuilder實例，用來控制將哪些接口保羅給swagger管理
     * 本例採用掃描指定包路徑來ding'yi要建立地api地目錄
     * @return
     */
    @Bean
    public Docket CreateRestApi(){
        return  new Docket(DocumentationType.SWAGGER_2).
                apiInfo(apiInfo()).
                select().
                apis(RequestHandlerSelectors.basePackage("com.demo.swagger.controller")).
                paths(PathSelectors.any()).
                build();
    }

    /**
     * 創建api的基本信息，這些信息會展示在文檔頁面
     * 訪問地址：http://項目實際地址/swagger-ui.html
     * @return
     */
    private ApiInfo apiInfo(){
            return new ApiInfoBuilder().
                    title("在spring boot中使用swagger2 來構建RESTFUL APIS").
                    description("更多關注com.gz").termsOfServiceUrl("http://www.baidu.com").
                    contact("sunf").version("1.0").build();
    }
}

3. controller層調用樣例

package com.demo.swagger.controller;

import com.alibaba.fastjson.JSONObject;
import com.demo.swagger.entity.User;
import com.demo.swagger.mapper.UserDao;
import io.swagger.annotations.*;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.*;

import javax.annotation.Resource;
import java.util.HashMap;
import java.util.Map;

@RestController
@RequestMapping("user")
@Api("用戶信息操作接口集")
public class HelloController {

    @Autowired
    UserDao userDao;

    /**
     * @GetMapping 可以不設置參數 這裏攔截的是 /user/  Get
     * @ApiOperation value 用於描述這個接口的功能，notes 用戶更詳細地說明用法
     * @ApiImplicatitParam 用於說明一個入參信息，paramType 描述參數存放地位置（header、query、path、body、form）
     * name 描述參數的名稱     value 描述參數的含義   dataType 描述參數的基本類型
     * @ApiImplicatitParams 用於說明一組入參信息，當有多個入參時需要用這個將上一個註解包含起來
     * @ApiResponse 描述返回的信息， code 指的狀態編碼， message 指的具體描述， response 能返回一個實體類， 這個註解一般用於說明異常的情況
     * @ApiResponses 可以包含多個上一個註解，上一個註解單獨使用時沒有生效
     * @param userName
     * @return
     */
    @GetMapping
    @ApiOperation(value = "獲取用戶信息", notes = "根據用戶名獲取用戶信息")
    @ApiImplicitParam(paramType = "query", name = "userName", value = "用戶名", dataType = "String")
    @ApiResponses({
            @ApiResponse(code = 401, message = "沒找到用戶", response = Exception.class)
    })
    public User getUserInfo(@RequestParam String userName) {
        return userDao.selectByUserName(userName);
    }

    /**
     * 添加用戶信息
     * @param user
     * @return
     */
    @PostMapping
    @ApiOperation(value = "添加用戶", notes = "用戶名、密碼 必填")
    @ApiResponses({
            @ApiResponse(code = 401, message = "錯誤的用戶", response = User.class)
    })
    public Object addUserInfo(@RequestBody @ApiParam(name = "用戶對象", value = "傳入json格式", required = true) User user){
        userDao.insertUser(user);
        return userDao.selects();
    }

    /**
     * 修改用戶密碼
     * @param userName
     * @param password
     * @return
     */
    @PutMapping
    @ApiOperation(value = "修改用戶密碼", notes = "輸入用戶名和密碼")
    @ApiImplicitParams({
            @ApiImplicitParam(paramType = "query", name = "userName", value = "用戶名", dataType = "string"),
            @ApiImplicitParam(paramType = "query", name = "password", value = "密碼", dataType = "string")
    })
    @ApiResponses({
            @ApiResponse(code = 500, message = "沒有找到用戶", response = User.class)
    })
    public Object updateUserPassword(@RequestParam String userName, @RequestParam String password){
        userDao.updateUserPassword(userName, password);
        return userDao.selectByUserName(userName);
    }

    /**
     * 刪除指定用戶
     * @param userName
     * @return
     */
    @DeleteMapping
    @ApiOperation(value = "刪除用戶", notes = "根據指定用戶名刪除用戶")
    @ApiImplicitParam(paramType = "query", name = "userName", value = "用戶名")
    public Object deleteUser(@RequestParam String userName){
        userDao.deleteByUserName(userName);
        return userDao.selects();
    }
}

4. 附上註解說明

   1. 與模型相關的註解
      兩個註解：
      @ApiModel：用在模型類上，對模型類做註釋；
      @ApiModelProperty：用在屬性上，對屬性做註釋
   2. 與接口相關的註解
      六個註解：
      @Api：用在controller上，對controller進行註釋；
      @ApiOperation：用在API方法上，對該API做註釋，說明API的作用；
      @ApiImplicitParams：用來包含API的一組參數註解，可以簡單的理解爲參數註解的集合聲明；
      @ApiImplicitParam：用在@ApiImplicitParams註解中，也可以單獨使用，說明一個請求參數的各個方面，該註解包含的常用選項有：
      paramType：參數所放置的地方，包含query、header、path、body以及form，最常用的是前四個。
      name：參數名；
      dataType：參數類型，可以是基礎數據類型，也可以是一個class；
      required：參數是否必須傳；
      value：參數的註釋，說明參數的意義；
      defaultValue：參數的默認值；
      @ApiResponses：通常用來包含接口的一組響應註解，可以簡單的理解爲響應註解的集合聲明；
      @ApiResponse：用在@ApiResponses中，一般用於表達一個錯誤的響應信息
      code：即httpCode，例如400
      message：信息，例如"請求參數沒填好"

5. 個人總結

   1. @Api 和 @ApiOperation 這兩個註解是必須的，分別加載類上和方法上
   2. @ApiImplicitParam 在使用時，paramType 一般使用query， 但在涉及對象傳入時就需要在對象上添加@ApiModel，在對象屬性上加@ApiModelproperty，並在傳入時，採用類似這種方式：

   public Object addUserInfo(
   @RequestBody @ApiParam(name = "用戶對象", value = "傳入json格式", required = true) 
   User user) { }
   

   3. @ApiResponses 一般時結合我們自定義的返回結果集類來使用，並且 不能單獨寫@ApiResponse， 必須要在外面包含一層@ApiResponses