springboot整合swagger實戰（基礎版）

1. 前言說明

本文主要介紹springboot整合swagger的全過程，從開始的swagger到Knife4j的進階之路；Knife4j是swagger-bootstarp-ui的升級版，包括一些增強功能，關於Knife4j下篇文章中著重介紹
swagger特點：

1. Api框架
2. restful Api文件線上自動生成工具
3. 可以直接執行，線上測試api介面
4. 支援多種語言：java、php...

2. 實戰步驟

(1) 搭建springboot專案

• springboot搭建專案就不介紹了，如果需要springboot整合swagger原始碼的，可以去我的倉庫檢視下載：點選跳轉

(2) 新增依賴

<!-- swagger2 -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
</dependency>
<!-- swagger-ui，原生swagger-Ui介面，訪問字尾（預設的）：swagger-ui.html-->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
</dependency>
<!-- bootstrap-ui,只是在改變頁面效果，訪問字尾：doc.html -->
<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>swagger-bootstrap-ui</artifactId>
    <version>1.9.2</version>
</dependency>

• springfox-swagger-ui和swagger-bootstrap-ui都是純swagger-ui的ui皮膚專案，渲染頁面的，作用是一樣的，只是swagger-bootstarp-ui在原來的基礎上做了頁面優化，頁面更符合中國人的閱讀習慣；
• 其實兩種都不介意使用，因為springfox-swagger-ui原生的比較醜，功能也不齊全（不能匯出，不能搜尋...），swagger-bootstrap-ui已經停更了，最終版本是1.9.6；所有推薦使用使用最新的Knife4j，下邊文章中著重介紹！！！
• 兩種UI頁面比較
  

(3) 註解標註

1. 匯入依賴之後，只要再啟動類上開啟註解@EnableSwagger2即可，就可以訪問UI頁面了；如果有自定義的配置類，可以標註到配置類上。
2. UI頁面可以訪問，但是需要使用其他註解來標註類，方法，引數，才可以看到介面等資訊，註解後邊一一羅列！！！
3. 頁面中有好多初始化的設定，如果需要修改為自己的，就需要新增配置類，就是第四步編寫配置

(4) 編寫配置

package com.ruyidan.swagger.config;

import java.util.ArrayList;

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.core.env.Environment;
import org.springframework.core.env.Profiles;
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: SwaggerConfig
 * @Description:
 * @Author: dangbo
 * @Date: 2021/3/25 14:13
 * @Version
 */
@Configuration
@EnableSwagger2
public class SwaggerConfig {
  @Autowired
  private Environment environment;

  @Bean
  public Docket docket() {
      // 設定顯示的swagger環境資訊
      Profiles profiles = Profiles.of("dev", "test");
      // 判斷是否處在自己設定的環境當中
      boolean flag = environment.acceptsProfiles(profiles);

      return new Docket(DocumentationType.SWAGGER_2)
              .apiInfo(apiInfo())
              .groupName("分組名稱")  // 配置api文件的分組
              .enable(flag)  // 配置是否開啟swagger
              .select()
              .apis(RequestHandlerSelectors.basePackage("com.ruyidan.swagger.controller")) //配置掃描路徑
              .paths(PathSelectors.any()) // 配置過濾哪些
              .build();
  }

  // api基本資訊
  private ApiInfo apiInfo() {
      return new ApiInfo("dxiaodang's swagger",
              "測試swagger-ui",
              "v1.0",
              "http://mail.qq.com",
              new Contact("dangbo", "http://mail.qq.com", "145xxxxx@qq.com"),  //作者資訊
              "Apache 2.0",
              "http://www.apache.org/licenses/LICENSE-2.0",
              new ArrayList());
  }
}

✌️ 注意點： ✌️

• 如果只需要在dev和test環境開啟swagger，就使用springboot的Environment例項來判斷當前配置檔案時使用的哪種；
• 如果需要配置多個分組，就要建立多個docket例項；
• 如果頁面無法正常訪問， 請看是否配置攔截器了，是不是因為攔截器攔截了請求

(5) 啟動服務驗證
略...

3. 常用註解

1. 實體類： ApiModel、實體屬性：ModelProperty
2. Controller類:Api
3. 介面方法的說明：ApiOperation
4. 方法引數的說明：@ApiImplicitParams、@ApiImplicitParam
5. 方法返回值的說明：@ApiResponses @ApiResponse
6. ParamType和dataType區別

• ParamType：表示引數放在哪個位置
  • header-->請求引數的獲取：@RequestHeader(程式碼中接收註解)
  • query-->請求引數的獲取：@RequestParam(程式碼中接收註解)
  • path（用於restful介面）-->請求引數的獲取：@PathVariable(程式碼中接收註解)
  • body-->請求引數的獲取：@RequestBody(程式碼中接收註解)
  • form（不常用）
• dataType：引數型別，可傳基本型別、類、泛型類等

4. 常見問題彙總

(1) swagger-ui.html訪問報錯，或doc.html訪問之後為空：==未使用@EnableSwagger註解開啟服務
Unable to infer base url. This is common when using dynamic servlet registration or when the API is behind an API Gateway. The base url is the root of where all the swagger resources are served. For e.g. if the api is available at http://example.org/api/v2/api-docs then the base url is http://example.org/api/. Please enter the location manually:


(2) 自定義配置後，頁面沒有一個介面： 檢查docket配置的掃描路徑和配置過濾哪些，是否配置錯誤導致
(3) 頁面就會出現Could not render e, see the console，或請確保swagger資源介面正確：配置檔案問題，配置dev和test環境開啟swagger，其他環境關閉導致的
Could not render e, see the console
請確保swagger資源介面正確

(2) 自定義配置後，頁面沒有一個介面： 檢查docket配置的掃描路徑和配置過濾哪些，是否配置錯誤導致