定義 Swagger 配置類，自定義 API 文件資訊

Swagger是一個規範和完整的框架，用於生成、描述、呼叫和視覺化 RESTful 風格 的 Web 服務,在實際開發中，常用Swagger-API介面文件自動生成工具，幫助專案自動生 成和維護介面文件。

它具有以下特點：

• 及時性：介面變更後，Api文件同步自動更新

• 規範性：遵守RESTful風格，保證介面的規範性，如介面的地址，請求方式，引數及 響應

​ 格式和錯誤資訊

• 一致性：介面資訊一致，不會出現因開發人員拿到的文件版本不一致而導致分歧

• 可測性：直接在介面文件上進行測試，可以線上測試Api介面，方便理解業務

在 SpringBoot 專案中應用 Swagger

1. 在 SpringBoot 專案中應用 Swagger

    <!--   swagger 核心依賴-->
    <dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-swagger2</artifactId>
        <version>2.9.2</version>
    </dependency>
    <!--   swagger ui 依賴-->
    <dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-swagger-ui</artifactId>
        <version>2.9.2</version>
    </dependency>
 

2. 開啟swagger

   在專案的啟動類上加上@EnableSwagger2註解，表示開啟Swagger，同時它也支援自 定義UI頁面的一些資訊。

3. 啟動專案，訪問API線上文件頁面

   http://localhost:8080/swagger-ui.html

4. 定義 Swagger 配置類，自定義 API 文件資訊

   /**
    *  Swagger配置類
    */
   @Configuration
   public class SwaggerConfig {
       public static final String SWAGGER_SCAN_BASE_PACKAGE = "com.example.demo";
   
       public static final String VERSION = "1.0.0";
   
       @Bean
       public Docket createRestApi() {
           return new Docket(DocumentationType.SWAGGER_2)
                   .apiInfo(apiInfo())
                   .select()
                   .apis(RequestHandlerSelectors.basePackage(SWAGGER_SCAN_BASE_PACKAGE))
                   .paths(PathSelectors.any()) // 可以根據url路徑設定哪些請求加入文件，忽略哪些請求
                   .build();
       }
   
       private ApiInfo apiInfo() {
           return new ApiInfoBuilder()
                   .title("我的第一個專案")   //設定文件的標題
                   .description("*** API 介面文件")   // 設定文件的描述
                   .version(VERSION)   // 設定文件的版本
                   .contact(new Contact("****", "", "***@qq.com"))
                   .termsOfServiceUrl("http://***.***.***")   // 配置服務網站，
                   .build();
       }
   
   }
    
   

5. 通過註解來完善API文件

   （1）@Api註解： 用來標記當前 Controller 的功能。

​ （2）@ApiOperation註解：用來標記一個方法的作用。

​ (3) @ApiImplicitParam註解：用來描述一個引數，可以配置引數的中文含義，也 可以給引數設定預設值，這樣在介面測試的時候可以避免手動輸入；

​ (4) @ApiModel ：用在實體類上，主要屬性有description(描述)、parent(父類)、 subTypes、value、discriminator等；

​ @ApiModelProperty：用在實體類屬性上，主要屬性有access、accessMode、 allowableValues、allowEmptyValue(是否允許為空)、dataType(資料型別)、example(示 例)、hidden(是否隱藏)、name(名稱)、notes、required(是否必需)、value(說明)等。