定義 Swagger 配置類，自定義 API 文檔信息

定義 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(說明)等。