一、是什麼

　　當下很多公司都採取前後端分離的開發模式，前端和後端的工作由不同的工程師完成。在這種開發模式下，維持一份及時更新且完整的 Rest API 文件將會極大的提高我們的工作效率。傳統意義上的文件都是後端開發人員手動編寫的，相信大家也都知道這種方式很難保證文件的及時性，這種文件久而久之也就會失去其參考意義，反而還會加大我們的溝通成本。而 Swagger 給我們提供了一個全新的維護 API 文件的方式。

二、為什麼要使用它

　　1、程式碼變更，文件跟著程式碼變、只需要少量的註解Swagger就可以根據程式碼自動的生成API文件，很好的保證了文件的實時性。

　　2、跨語言，Swagger支援40多種語言。

　　3、Swagger UI 呈現出來的是一份可以互動的API文件，我們可以直接在文件頁面嘗試API的呼叫，省去了準備複雜的呼叫引數的過程。

　　4、還可以將文件規範匯入相關的工具裡面（例如：Postman、SoapUI）、這些工具將會為我們自動地建立自動化測試。

三、怎麼用

　　1、在專案pom.xml裡面加入Swagger2相關的依賴

        <!--swagger2配置-->
        <dependency>
            <groupId>io.springfox</groupId>
            <
 
artifactId>springfox-swagger-ui</artifactId>
            <version>2.4.0</version>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>
 
2.4.0</version>
        </dependency>
        <dependency>
            <groupId>com.github.xiaoymin</groupId>
            <artifactId>swagger-bootstrap-ui</artifactId>
            <version>1.6</version>
        </dependency>

　　2、新建Swagger2的配置類

package com.zhouhong.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.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
/**
 * @ClassName: Swagger2
 * @Description:
 * @Author: 周紅
 * @NickName: Tom-shuhu
 * @Date: Created in 2020/12/15
 **/
@Configuration
@EnableSwagger2
public class Swagger2 {
    //   http://localhost:8088/swagger-ui.html  原路徑
    //   http://localhost:8088/doc.html  原路徑
    //配置swagger2核心配置
    @Bean
    public Docket createRestApi(){
        return new Docket(DocumentationType.SWAGGER_2) //指定api型別位swagger2
            .apiInfo(apiInfo())                        //用於定義api文件彙總資訊
                .select().apis(RequestHandlerSelectors
                        .basePackage("com.zhouhong.controller")) //指定生成文件的controller
                .paths(PathSelectors.any())　　　　　　
                .build();
    }
    private ApiInfo apiInfo(){
        return new ApiInfoBuilder()
                .title("Tom-shushu 的專案介面api")  //文件標題
                .contact(new Contact("周紅",  //作者
                        "www.zhouhong.icu",　　
                        "[email protected]")) //聯絡人
                .description("Tom-shushu 的專案api介面")//詳細資訊
                .version("1.0.0")//文件版本號
                .termsOfServiceUrl("www.zhouhong.icu")//網站地址
                .build();
    }
}

　　文件配置說明：

　　a.為任何介面生成API文件，這種方式不必在介面方法上加任何註解，方便的同時也會因為沒有新增任何註解所以生成的API文件也沒有註釋，可讀性不高。

    @Bean
    public Docket createRestApi(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                //為任何介面生成API文件
                .apis(RequestHandlerSelectors.any())
                .paths(PathSelectors.any())
                .build();
    }

　　b.為當前配置的包下controller生成API文件

.apis(RequestHandlerSelectors.basePackage("com.troila"))

　　c.為有@Api註解的Controller生成API文件

.apis(RequestHandlerSelectors.withClassAnnotation(Api.class))

　　d.為有@ApiOperation註解的方法生成API文件

.apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))

三、常見註解簡介

 @Api：修飾整個類，描述Controller的作用
 @ApiOperation：描述一個類的一個方法，或者說一個介面
 @ApiParam：單個引數描述
 @ApiModel：用物件實體來作為入參
 @ApiProperty：用物件接實體收引數時，描述物件的一個欄位
 @ApiResponse：HTTP響應其中1個描述
 @ApiResponses：HTTP響應整體描述
 @ApiIgnore：使用該註解忽略這個API
 @ApiError ：發生錯誤返回的資訊
 @ApiImplicitParam：一個請求引數
 @ApiImplicitParams： 多個請求引數

四、演示（為方便我使用了上面第一種配置）

　　1、使用原路徑訪問

　　2、原路徑除錯

　　3、doc模式訪問

4、doc模式除錯