首先，老規矩，我們在接觸新事物的時候, 要對之前學習和了解過的東西做一個總結。

01

痛     苦

不做、不行

　　之前，前後端分離的系統由前端和後端不同的編寫，我們苦逼的後端工程師會把自己已經寫完的API介面，寫一個介面文件給到我們前端工程師，前端工程師拿到介面文件之後，根據介面文件規定的URL、請求方式(POST或GET)、請求引數、返回結果(成功或失敗，失敗時，返回的狀態分別代表什麼意思)，來對接我們後端提供的API介面，如果提供的介面文件有問題，那麼同樣的，前端對接時，也會出現問題，前端會說是後端提供的介面文件的問題，後端覺得我可能程式更新了，沒有及時更新介面文件。其實，不管是前端還是後端，都希望有一個好的介面文件，能隨著程式的迭代不斷更新的介面文件。

而寫介面文件這種沒有技術含量又苦惱的事兒，對於後端來說無疑是噩夢一般，API介面少，沒幾個，可能半個點一個點就完事兒了，如果API介面很多，比如說整個訂單系統的介面，寫介面文件這種事兒可能會耗上一天，兩天，甚至三天，最後寫完還不一定是對的，那個痛啊。

02

邂      逅

有痛點、丟擲來

之前寫API文件的方式各種各樣，wiki、word、excel、text等等各種方式，萬物皆可盤。

比如word：

對，word要把目錄給人家定義好，要不會被噴的。
再比如excel：

        還有text：

千篇一律， 能不能再亂一點，前端已經提這40米的大砍刀在向你走來。

有沒有自動生成API文件的外掛呢？答：有，還自帶各種外掛

關於SwaggerSwagger是一個功能強大且易於使用的API開發人員工具套件，適用於團隊和個人，可在整個API生命週期（從設計和文件到測試和部署）中進行開發。

Swagger由開放原始碼，免費和市售工具共同組成，它使任何人（從技術工程師到街頭智慧產品經理）都可以構建每個人都喜歡的驚人API。

Swagger由SmartBear Software構建，後者是團隊軟體質量工具的領導者。SmartBear落後於軟體領域的一些知名公司，包括Swagger，SoapUI和QAComplete。

在Swagger官網上提供了幾種工具，可以通過整合的方式來實現我們想要的效果。

　　Swagger Inspector:類似postman的一種API除錯工具，可以點選URL，檢視如何使用。https://swagger.io/docs/swagger-inspector/how-to-use-swagger-inspector/。

　　Swagger Codegen:是一個開原始碼生成器，可直接從Swagger定義的RESTful API構建伺服器存根和客戶端SDK。Swagger Codegen的原始碼可以在GitHub中找到，點選URL，檢視如何使用。https://swagger.io/docs/open-source-tools/swagger-codegen/。

       Swagger Editor:是一個開源編輯器，用於設計，定義和記錄Swagger規範中的RESTful API，點選URL檢視如何使用，https://swagger.io/docs/open-source-tools/swagger-editor/

       Swagger UI:提供了一個視覺化的UI頁面展示描述檔案。介面的呼叫方、測試、專案經理等都可以在該頁面中對相關介面進行查閱和做一些簡單的介面請求。該專案支援線上匯入描述檔案和本地部署UI專案，點選URL檢視如何使用，https://swagger.io/docs/open-source-tools/swagger-ui/usage/installation/

03

接     觸

收入囊中

      Swagger是什麼我們已經介紹完了，下面我們通過程式碼示例來講解如何與Springboot結合使用。

1、引入Swagger相關jar包(Springboot相關jar自行引入)

　　<dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-swagger2</artifactId>
        <version>2.9.2</version>
    </dependency>
    <dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-swagger-ui</artifactId>
        <version>2.9.2</version>
    </dependency>

2、建立啟動類，設定啟動引數，首先建立一個class，命名為SwaggerApplication，其中managerPackage為Swagger要管理的包目錄，比如com.user.api.controller，從header獲取引數名為Authorization的值，可以用於驗證許可權(如果顯示不完整請左右滑動檢視全部)。

 1 /**
 2  * Swagger2配置類
 3  * 在與spring boot整合時，放在與Application.java同級的目錄下。
 4  * 通過@Configuration註解，讓Spring來載入該類配置。
 5  * 再通過@EnableSwagger2註解來啟用Swagger2。
 6  */
 7 @Configuration
 8 @EnableSwagger2
 9 public class SwaggerApplication{
10 ​
11   @Value(value = "${swagger.manager.package}")
12   private String managerPackage;
13 ​
14   /**
15    * 建立API應用
16    * apiInfo() 增加API相關資訊
17    * 通過select()函式返回一個ApiSelectorBuilder例項,用來控制哪些介面暴露給Swagger來展現，
18    * 本例採用指定掃描的包路徑來定義指定要建立API的目錄。
19    *
20    * @return
21    */
22   @Bean
23   public Docket createRestApi(){
24     ParameterBuilder aParameterBuilder = new ParameterBuilder();
25     aParameterBuilder
26         .parameterType("header") //引數型別支援header, cookie, body, query etc
27         .name("Authorization") //引數名
28         .defaultValue("Authorization") //預設值
29         .description("token")
30         .modelRef(new ModelRef("string"))//指定引數值的型別
31         .required(false).build(); //非必需，這裡是全域性配置，然而在登陸的時候是不用驗證的
32     List<Parameter> aParameters = new ArrayList<Parameter>();
33     aParameters.add(aParameterBuilder.build());
34     return new Docket(DocumentationType.SWAGGER_2)
35         .groupName("v1")
36         .select()
37         .apis(RequestHandlerSelectors.basePackage(basePackage))
38         .paths(PathSelectors.any())
39         .build()
40         .apiInfo(apiInfo())
41         .globalOperationParameters(aParameters);
42   }
43 ​
44   public ApiInfo apiInfo(){
45     return new ApiInfoBuilder()
46         .title("使用者管理API介面文件")
47         .description("使用者管理API介面文件")
48         .termsOfServiceUrl("")
49         .contact("sunf")
50         .version("1.0")
51         .build();
52   }
53 }

3、新增實體類引用，PS：引用只新增DTO、VO，Entity不需要，class頭註解@ApiModel，申明該類被Swagger解析，@ApiModelProperty宣告各欄位屬性的含義。

 1 @ApiModel(description = "使用者資訊")
 2 @Data
 3 public class Users {
 4 ​
 5   @ApiModelProperty(value = "使用者ID")
 6   private String id;
 7   @ApiModelProperty(value = "使用者姓名")
 8   private String userName;
 9   @ApiModelProperty(value = "年齡")
10   private String age;
11   @ApiModelProperty(value = "性別")
12   private String sex;
13   @ApiModelProperty(value = "地址")
14   private String address;
15   @ApiModelProperty(value = "電話")
16   private String phone;
17 ​
18 }

4、宣告Controller，暴漏API介面，如果一個介面沒有宣告明確的呼叫方式(POST或GET)method = RequestMethod.POST，Swagger預設會把所有的呼叫方式都列出來。

@RestController
@RequestMapping("/user")
@Api(value = "使用者相關介面",description = "使用者資訊")
public class UserController {
​
  @Autowired
  private UserService userService;
  /**
   * 獲取使用者詳情
   * @param userId
   * @return
   */
  @ApiOperation(value = "獲取使用者詳情", notes = "根據使用者ID獲取使用者詳情")
  @RequestMapping(value = "/get",method = RequestMethod.POST)
  public Users get(String userId){
    return userService.get(userId);
  }
​
  /**
   * 獲取所有使用者
   * @return
   */
  @ApiOperation(value = "獲取所有使用者", notes = "獲取所有使用者列表")
  @RequestMapping(value = "/getUserAllList",method = RequestMethod.POST)
  public List<Users> getUserAllList(){
    return userService.getUserAllList();
  }
}

PS:未指定訪問方式是這樣的

5、到此Swagger的配置基本完成，啟動Springboot的服務，訪問Swagger內建的web頁面，可以看到我們暴漏的所有API和呼叫方式，訪問地址：http://localhost:8081/swagger-ui.html

6、點選獲取使用者詳情的介面，try it out ,可以針對此介面進行訪問除錯，點選Model可以檢視使用者實體

7、如果是頁面樣式不滿意，我們可以自定義頁面樣式，現在github已經有道友分享了自定義的ui，如何使用請檢視，https://github.com/caspar-chen/swagger-ui-layer，下圖是新的UI，是不是你的菜。

小結：Swagger，就是把相關的資訊儲存在它定義的描述檔案裡面（yml或json格式），再通過維護這個描述檔案可以去更新介面文件，以及生成各端程式碼。而Springfox-swagger,則可以通過掃描程式碼去生成這個描述檔案，連描述檔案都不需要再去維護了。所有的資訊，都在程式碼裡面了。程式碼即介面文件，介面文件即程式碼。

微信掃一掃關注我，分享給其他人，一起成長