SpringBoot整合Swagger UI,别再寫開發文檔了

開發文檔的弊端

        随着軟體開發的分工明确化，前後端分離成為越來越流行的一種開發形式，這樣可以更好的提高開發效率和項目進度。可是在開發web項目時，因為需求變動等原因，免不了要修改背景代碼，可能是修改了方法簽名（方法名和參數清單）,可能是新增或者删除了方法,結果開發文檔忘記更新了，前端開發時，看着錯誤的文檔開發，發現接口參數不對，或者接口不存在，然後就噼裡啪啦的各種問，結果才發現，原來罪魁禍首是忘記更新開發文檔。而且，多次修改開發文檔，自己也不知道哪一個是最新的了。此時，你會問可以不寫開發文檔還能保證接口的實時性與準确性嗎？答案是可以的,為解決開發人員的痛點，swagger  UI應運而生。

認識Swagger

        那麼Swagger到底是什麼玩意？又能幹什麼？

Swagger 是一個規範和完整的架構，用于生成、描述、調用和可視化 RESTful 風格的 Web 服務。總體目标是使用戶端和檔案系統作為伺服器以同樣的速度來更新檔案的方法，參數和模型緊密內建到伺服器端的代碼，允許API來始終保持同步。

 作用：接口的文檔線上自動生成 ；功能測試。

說白了就是：1.實時更新API文檔    2.提供功能測試（post方法不用再使用postman測試了，這個還是非常友善的）

如何使用Swagger

        廢話不多說，先上代碼，任何架構，不都得先學會用再去了解原理的，哪個方法不是從helloWorld開始的，如果不是，那就是N個helloWorld。

1.在pom.xml裡面添加swagger 的maven依賴

<!-- swagger2 依賴開始 -->
        <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>
        <!-- swagger2 依賴結束 -->
           

2. 添加Swagger的配置類

/**
 * @author Tyler.Shi
 * @date 2018/8/24
 */
@Configuration
@EnableSwagger2
public class SwaggerConfig {

    /**
     * swagger2的配置檔案，這裡可以配置swagger2的一些基本的内容，
     * 比如掃描的包等等
     * @return docket
     */
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                //為目前包路徑 ,掃描controller包
                .apis(RequestHandlerSelectors.basePackage("com.example.swagger.controller"))
// 含有RestController的注解
// .apis(RequestHandlerSelectors.withClassAnnotation(RestController.class))
// 含有api的注解
// .apis(RequestHandlerSelectors.withClassAnnotation(Api.class))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                //頁面标題
                .title("Spring Boot 測試使用 Swagger2 建構RESTful API")
                //建立人
                .contact(new Contact("tyler.shi", "http://www.baidu.com", ""))
                //版本号
                .version("1.0")
                //描述
                .description("first demo for swagger")
                .build();
    }

}
           

3. 配置Swagger跳轉首頁

/**
 * @author Tyler.Shi
 * @date 2018/8/24
 */
@Controller
@RequestMapping(value = {"/home", "/"})
public class HomeController {

    @GetMapping(value = {"/", "api"})
    public String helloWorld() {
        return "redirect:/swagger-ui.html";
    }
}
           

4.  以上步驟完成了，就可以啟動項目了，如果沒有配置啟動端口，那麼預設的就是8080，浏覽器輸入localhost:8080就會跳轉到首頁

5. 到這一步你已經完成Swagger的基本配置和使用了，為了讓Swagger UI文檔更具可讀性（讓前端開發人員一看就懂），下面我們來介紹一下Swagger的幾個常用注解

 @Api()用于類:表示辨別這個類是swagger的資源  裡面可選的 注釋有value ，description,tags,其中tags是用來歸類的，具有相同值的tags會在API頁面中放在一起

@ApiOperation()用于方法: 表示一個http請求的操作

@ApiParam()用于方法、參數、字段說明：表示對參數的注釋

其中defaultValue為預設值，不傳值時預設為helloWorld;   allowableValues為可選值，如果參數為枚舉，可以考慮使用

@ApiModelProperty()用于方法、字段：表示對model屬性的說明或者資料操作更改 

/**
 * @author Tyler.Shi
 * @date 2018/8/28
 */
@Data
@ApiModel("User")
public class User {

    @ApiModelProperty(value = "使用者id")
    private Integer id;
    @ApiModelProperty(value = "使用者名")
    private String name;
    @ApiModelProperty(value = "年齡")
    private Integer age;
    @ApiModelProperty(value = "手機号")
    private String phone;
}
           

這裡就介紹一下常用的幾個注解吧，還有好多其他的注解這裡就不介紹了，感興趣的小夥伴自行找資料學習。