一.瞭解swagger2和lombok

（1）Swagger 是一個規範和完整的框架，用於生成、描述、呼叫和視覺化 RESTful 風格的 Web 服務。總體目標是使客戶端和檔案系統作為伺服器以同樣的速度來更新。檔案的方法，引數和模型緊密整合到伺服器端的程式碼，允許API來始終保持同步。Swagger 讓部署管理和使用功能強大的API從未如此簡單。

swagger2註解詳解

@Api：用在請求的類上，表示對類的說明
  tags="說明該類的作用，可以在UI介面上看到的註解，如果tags多個值，會生成多個list"
  value="該引數沒什麼意義，在UI介面上也看不到，所以不需要配置"

@ApiOperation：用在請求的方法上，說明方法的用途、作用
  value="說明方法的用途、作用"
  notes="方法的備註說明"

@ApiParam：單個引數描述
- name：引數名
- value：引數說明
- required：是否必填

@ApiModel：用物件來接收引數
- value：表示物件名
- description：對物件的描述
@ApiModelProperty：用物件接收引數時，描述物件的一個欄位
  - value：欄位說明
  - name：重寫屬性名
  - dataType：重寫屬性型別
  - example：舉例說明
  - hidden：隱藏

@ApiIgnore：使用該註解忽略這個API，用於類或者方法上

@ApiImplicitParams：用在請求的方法上，表示一組引數說明
  @ApiImplicitParam：用在@ApiImplicitParams註解中，指定一個請求引數的各個方面
      name：引數名
      value：引數的漢字說明、解釋
      required：引數是否必須傳
      paramType：引數放在哪個地方
          · header --> 請求引數的獲取：@RequestHeader
          · query --> 請求引數的獲取：@RequestParam
          · path（用於restful介面）--> 請求引數的獲取：@PathVariable
          · body（不常用）
          · form（不常用）    
      dataType：引數型別，預設String，其它值dataType="Integer"       
      defaultValue：引數的預設值
 

（2）lombok是一個可以通過簡單的註解的形式來幫助我們簡化消除一些必須有但顯得很臃腫的 Java 程式碼的工具。比如在實體類中我們需要手動去建立get/set方法，建構函式之類的，Lombok的作用就是幫助我們在編譯原始碼時自動生成這些方法，只需要我們使用註解即可。

Lombok註解詳解：

Lombok主要常用的註解有：@Data,@getter,@setter,@NoArgsConstructor,@AllArgsConstructor,@ToString,@EqualsAndHashCode
,@Slf4j,@Log4j。我們一個一個來看：

@Data註解：在JavaBean或類JavaBean中使用，這個註解包含範圍最廣，它包含getter、setter、
NoArgsConstructor註解，即當使用當前註解時，會自動生成包含的所有方法；

@getter註解：在JavaBean或類JavaBean中使用，使用此註解會生成對應的getter方法；

@setter註解：在JavaBean或類JavaBean中使用，使用此註解會生成對應的setter方法；

@NoArgsConstructor註解：在JavaBean或類JavaBean中使用，使用此註解會生成對應的無參構造方法；

@AllArgsConstructor註解：在JavaBean或類JavaBean中使用，使用此註解會生成對應的有參構造方法；

@ToString註解：在JavaBean或類JavaBean中使用，使用此註解會自動重寫對應的toStirng方法；

@EqualsAndHashCode註解：在JavaBean或類JavaBean中使用，使用此註解會自動重寫對應的equals方法和
hashCode方法；

@Slf4j：在需要列印日誌的類中使用，當專案中使用了slf4j列印日誌框架時使用該註解，會簡化日誌的列印流
程，只需呼叫info方法即可；

@Log4j：在需要列印日誌的類中使用，當專案中使用了log4j列印日誌框架時使用該註解，會簡化日誌的列印流
程，只需呼叫info方法即可；

在使用以上註解需要處理引數時，處理方法如下（以@ToString註解為例，其他註解同@ToString註解）：

@ToString(exclude="column")

意義：排除column列所對應的元素，即在生成toString方法時不包含column引數；

@ToString(exclude={"column1","column2"})

意義：排除多個column列所對應的元素，其中間用英文狀態下的逗號進行分割，即在生成toString方法時不包含多個column引數；

@ToString(of="column")

意義：只生成包含column列所對應的元素的引數的toString方法，即在生成toString方法時只包含column引數；；

@ToString(of={"column1","column2"})

意義：只生成包含多個column列所對應的元素的引數的toString方法，其中間用英文狀態下的逗號進行分割，
即在生成toString方法時只包含多個column引數。
 

使用lombok注意的幾個點：

（1）、當你的IDE是Idea時，要注意你的Idea是支援Lombok的，如果不支援請更換2017版本嘗試。

（2）、在使用Lombok時，你的編輯器可能會報錯，這時請在你的IDE中安裝Lombok外掛（如果使用的Idea則直接
搜尋Lombok外掛，選擇星級最高的，直接安裝就是，其他Ide類同）。

（3）、引數的處理往往都是根據專案需求來進行，請妥善處理引數。

（4）、如果你無法訪問Lombok官網，你可以從這篇博文中將Maven座標照著自己打進去，或者你也可以訪問
Maven的中央倉庫搜尋Lombok，將Maven座標複製進去即可。

二.搭建springboot，lombok，swagger2整合框架

新建springboot工程我就不多說了前面已經講過。先講一下pom的引用

1. Maven依賴匯入

<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>
<!-- https://mvnrepository.com/artifact/org.projectlombok/lombok -->
<dependency>
    <groupId>org.projectlombok</groupId>
    <artifactId>lombok</artifactId>
    <version>1.18.2</version>
    <scope>provided</scope>
</dependency>

2.springboot啟動項：加上@EnableSwagger2註解代表可以在springboot工程中使用Swagger2的註解

package com.example.swagger;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@SpringBootApplication       //等同於@[email protected][email protected]
@EnableSwagger2             //啟動swagger註解
public class SwaggerApplication {

	public static void main(String[] args) {
		SpringApplication.run(SwaggerApplication.class, args);
	}
}

3.Controller： 在這裡是swagger-ui需要展示的api，

package com.example.swagger.controller;

import com.example.swagger.vo.JsonResult;
import com.example.swagger.vo.User;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiImplicitParams;
import io.swagger.annotations.ApiOperation;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.*;
import springfox.documentation.annotations.ApiIgnore;
import java.util.*;


/**
 * Created By Liurenquan on 2018/11/17
 */
@RestController
public class SwaggerDemoController {

    // 建立執行緒安全的Map
    static Map<Integer, User> users = Collections.synchronizedMap(new HashMap<Integer, User>());

    /**
     * 根據ID查詢使用者
     * @param id
     * @return
     */
    @ApiOperation(value="獲取使用者詳細資訊", notes="根據url的id來獲取使用者詳細資訊")
    @ApiImplicitParam(name = "id", value = "使用者ID", required = true, dataType = "Integer", paramType = "path")
    @RequestMapping(value = "user/{id}", method = RequestMethod.GET)
    public ResponseEntity<JsonResult> getUserById (@PathVariable(value = "id") Integer id){
        JsonResult r = new JsonResult();
        try {
            User user = users.get(id);
            r.setResult(user);
            r.setStatus("ok");
        } catch (Exception e) {
            r.setResult(e.getClass().getName() + ":" + e.getMessage());
            r.setStatus("error");
            e.printStackTrace();
        }
        return ResponseEntity.ok(r);
    }

    /**
     * 查詢使用者列表
     * @return
     */
    @ApiOperation(value="獲取使用者列表", notes="獲取使用者列表")
    @RequestMapping(value = "users", method = RequestMethod.GET)
    public ResponseEntity<JsonResult> getUserList (){
        JsonResult r = new JsonResult();
        try {
            List<User> userList = new ArrayList<User>(users.values());
            r.setResult(userList);
            r.setStatus("ok");
        } catch (Exception e) {
            r.setResult(e.getClass().getName() + ":" + e.getMessage());
            r.setStatus("error");
            e.printStackTrace();
        }
        return ResponseEntity.ok(r);
    }

    /**
     * 新增使用者
     * @param user
     * @return
     */
    @ApiOperation(value="建立使用者", notes="根據User物件建立使用者")
    @ApiImplicitParam(name = "user", value = "使用者詳細實體user", required = true, dataType = "User")
    @RequestMapping(value = "user", method = RequestMethod.POST)
    public ResponseEntity<JsonResult> add (@RequestBody User user){
        JsonResult r = new JsonResult();
        try {
            users.put(user.getId(), user);
            r.setResult(user.getId());
            r.setStatus("ok");
        } catch (Exception e) {
            r.setResult(e.getClass().getName() + ":" + e.getMessage());
            r.setStatus("error");

            e.printStackTrace();
        }
        return ResponseEntity.ok(r);
    }

    /**
     * 根據id刪除使用者
     * @param id
     * @return
     */
    @ApiOperation(value="刪除使用者", notes="根據url的id來指定刪除使用者")
    @ApiImplicitParam(name = "id", value = "使用者ID", required = true, dataType = "Long", paramType = "path")
    @RequestMapping(value = "user/{id}", method = RequestMethod.DELETE)
    public ResponseEntity<JsonResult> delete (@PathVariable(value = "id") Integer id){
        JsonResult r = new JsonResult();
        try {
            users.remove(id);
            r.setResult(id);
            r.setStatus("ok");
        } catch (Exception e) {
            r.setResult(e.getClass().getName() + ":" + e.getMessage());
            r.setStatus("error");

            e.printStackTrace();
        }
        return ResponseEntity.ok(r);
    }

    /**
     * 根據id修改使用者資訊
     * @param user
     * @return
     */
    @ApiOperation(value="更新資訊", notes="根據url的id來指定更新使用者資訊")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "id", value = "使用者ID", required = true, dataType = "Long",paramType = "path"),
            @ApiImplicitParam(name = "user", value = "使用者實體user", required = true, dataType = "User")
    })
    @RequestMapping(value = "user/{id}", method = RequestMethod.PUT)
    public ResponseEntity<JsonResult> update (@PathVariable("id") Integer id, @RequestBody User user){
        JsonResult r = new JsonResult();
        try {
            User u = users.get(id);
            u.setUsername(user.getUsername());
            u.setAge(user.getAge());
            users.put(id, u);
            r.setResult(u);
            r.setStatus("ok");
        } catch (Exception e) {
            r.setResult(e.getClass().getName() + ":" + e.getMessage());
            r.setStatus("error");

            e.printStackTrace();
        }
        return ResponseEntity.ok(r);
    }

    @ApiIgnore//使用該註解忽略這個API
    @RequestMapping(value = "/ignore", method = RequestMethod.GET)
    public String  jsonTest() {
        return "ignore this interface!";
    }
}

這裡使用swagger的三種註解

(1) @ApiOperation：用在請求的方法上，說明方法的用途、作用 value="說明方法的用途、作用" notes="方法的備註說明"



(2) @ApiImplicitParams：用在請求的方法上，表示一組引數說明
    @ApiImplicitParam：用在@ApiImplicitParams註解中，指定一個請求引數的各個方面
      name：引數名
      value：引數的漢字說明、解釋
      required：引數是否必須傳
      paramType：引數放在哪個地方
          · header --> 請求引數的獲取：@RequestHeader
          · query --> 請求引數的獲取：@RequestParam
          · path（用於restful介面）--> 請求引數的獲取：@PathVariable
          · body（不常用）
          · form（不常用）    
      dataType：引數型別，預設String，其它值dataType="Integer"       
      defaultValue：引數的預設值

(3)  @ApiIgnore//使用該註解忽略這個API

4.swagger配置項

package com.example.swagger.config;

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;

/**
 * Created By Liurenquan on 2018/11/17
 */
@Configuration //用@Configuration註解該類，等價於XML中配置beans
public class Swagger2 {

    @Bean //用@Bean標註方法等價於XML中配置bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo()) // 用來建立該Api的基本資訊（這些基本資訊會展現在文件頁面中）
                .select() //函式返回一個 ApiSelectorBuilder 例項用來控制哪些介面暴露給Swagger2來展現
                .apis(RequestHandlerSelectors.basePackage("com.example.swagger.controller")) // 指明要展示的api在那個包下面
                .paths(PathSelectors.any()) // 對所有路徑進行監控
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("springboot利用swagger構建api文件") // api 標題
                .description("簡單優雅的restfun風格，https://blog.csdn.net/HaleyLiu123")  // api描述
                .termsOfServiceUrl("https://blog.csdn.net/HaleyLiu123") // 服務條款連結
                .version("1.0") // 版本號
                .build();
    }
}

5.實體類

package com.example.swagger.vo;

import lombok.AllArgsConstructor;
import lombok.Builder;
import lombok.Data;
import lombok.NoArgsConstructor;

import java.util.Date;

/**
 * Created By Liurenquan on 2018/11/17
 */
@Data  //生成Getter,Setter,equals,hashCode,toString方法
@Builder //表示可以進行Builder方式初始化
@AllArgsConstructor //提供一個包含所有變數的構造方法
@NoArgsConstructor //提供一個無參構造方法
public class User {

    private int id;
    private String username;
    private int age;
    private Date ctm;
}

6. 結果集類

package com.example.swagger.vo;

import lombok.AllArgsConstructor;
import lombok.Builder;
import lombok.Data;
import lombok.NoArgsConstructor;

/**
 * Created By Liurenquan on 2018/11/17
 */
@Data  //生成Getter,Setter,equals,hashCode,toString方法
@Builder //表示可以進行Builder方式初始化
@AllArgsConstructor //提供一個包含所有變數的構造方法
@NoArgsConstructor //提供一個無參構造方法
public class JsonResult {

    private String status = null;

    private Object result = null;
}

三. 結果展示

在parameters輸入資訊後，如果api要求傳參則傳，不要求則不傳。點選try it now可以進行介面除錯