Swagger使用總結

Swagger使用總結

1. Swagger是什麼？

官方說法：Swagger是一個規範和完整的框架，用於生成、描述、調用和可視化 RESTful 風格的 Web 服務。整體目標是使客戶端和文件系統做爲服務器以一樣的速度來更新。文件的方法，參數和模型緊密集成到服務器端的代碼，容許API來始終保持同步。

我的以爲，swagger的一個最大的優勢是能實時同步api與文檔。在項目開發過程當中，發生過屢次：修改代碼可是沒有更新文檔，前端仍是按照老舊的文檔進行開發，在聯調過程當中才發現問題的狀況（固然依據開閉原則，對接口的修改是不容許的，可是在項目不穩定階段，這種狀況很難避免）。

2. spring boot 集成 Swagger

目前維護的系統是基於springboot框架開發的，所以本文會詳細描述springboot與swagger集成的過程。

spring-boot系統集成swagger須要進行以下操做：

1. 添加maven依賴，須要在系統的pom中添加以下依賴：

   <dependency>
       <groupId>io.springfox</groupId>
       <artifactId>springfox-swagger2</artifactId>
       <version>2.2.2</version>
    </dependency>

2. 添加swagger配置文件，配置文件以下：

   @Configuration
   @EnableSwagger2
   public class SwaggerConfig {
   
       @Bean
       public Docket api() {
           return new Docket(DocumentationType.SWAGGER_2)
                   .select()  // 選擇那些路徑和api會生成document
                   .apis(RequestHandlerSelectors.any()) // 對全部api進行監控
                   .paths(PathSelectors.any()) // 對全部路徑進行監控
                   .build();
       }
   
   }

   經過註解EnableSwagger2聲明Swagger的可用性，此處會定義一個類型爲Docket的bean，
   關於docket類的說明以下：

   A builder which is intended to be the primary interface into the swagger-springmvc framework.Provides sensible defaults and convenience methods for configuration.

   Docket的select()方法會提供給swagger-springmvc framework的一個默認構造器（ApiSelectorBuilder），這個構造器爲配置swagger提供了一系列的默認屬性和便利方法。

3. 測試

   經過訪問：http://localhost:8080/your-app-root/v2/api-docs ，能測試生成的api是否可用。此時返回的是一個json形式的頁面，可讀性很差。能夠經過Swagger UI來生成一個可讀性良好的api頁面。具體作法就是，在pom中添加相關依賴。以下：

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

   再次訪問：http://localhost:8080/your-app-root/swagger-ui.html 就能夠看到可讀性較好的api文檔頁面。

4. 注意：

   1. http://localhost:8080/your-app-root/v2/api-docs 中your-app-root指的你的wabapp的根路徑，我目前的webapp就默認在根路徑下，因此地址是：http://localhost:8080/v2/api-docs
   2. spring-mvc上引用swagger須要作其餘相關的配置，具體請查看參考文獻
   3. swagger對restful風格的api支持的比較好，非restful風格的api支持的不是很好，對於非restful風格的api或者其餘語言（非java語言）能夠採用 http://editor.swagger 編輯器來收工完成相關的API編寫

參考文獻

1. swagger-2-documentation-for-spring-rest-api