Swagger使用總結

1. Swagger是什麼？

官方說法：Swagger是一個規範和完整的架構，用于生成、描述、調用和可視化 RESTful 風格的 Web 服務。總體目标是使用戶端和檔案系統作為伺服器以同樣的速度來更新。檔案的方法，參數和模型緊密內建到伺服器端的代碼，允許API來始終保持同步。

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

2. spring boot 內建 Swagger

目前維護的系統是基于springboot架構開發的，是以本文會較長的描述springboot與swagger內建的過程。

spring-boot系統內建swagger需要進行如下操作：

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

   gradle:compile('io.springfox:springfox-swagger2:2.2.2')           

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

2. 添加swagger配置檔案，配置檔案如下：

3. import org.springframework.context.annotation.Bean;

   import org.springframework.context.annotation.Configuration;

   import springfox.documentation.builders.PathSelectors;

   import springfox.documentation.builders.RequestHandlerSelectors;

   import springfox.documentation.spi.DocumentationType;

   import springfox.documentation.spring.web.plugins.Docket;

   import springfox.documentation.swagger2.annotations.EnableSwagger2;

   @Configuration
   @EnableSwagger2
   public class SwaggerConfig {
          
   <span class="hljs-meta"><span class="hljs-meta"><span class="hljs-meta">@Bean</span></span>
   <span class="hljs-function"><span class="hljs-keyword"><span class="hljs-function"><span class="hljs-keyword"><span class="hljs-function"><span class="hljs-keyword">public</span></span></span><span class="hljs-function"> Docket </span></span><span class="hljs-title"><span class="hljs-function"><span class="hljs-title"><span class="hljs-function"><span class="hljs-title">api</span></span></span></span><span class="hljs-params"><span class="hljs-function"><span class="hljs-params"><span class="hljs-function"><span class="hljs-params">()</span></span></span><span class="hljs-function"> </span></span>{
       <span class="hljs-keyword"><span class="hljs-keyword"><span class="hljs-keyword">return</span></span> <span class="hljs-keyword"><span class="hljs-keyword"><span class="hljs-keyword">new</span></span> Docket(DocumentationType.SWAGGER_2)
               .select()  <span class="hljs-comment"><span class="hljs-comment"><span class="hljs-comment">// 選擇那些路徑和api會生成document</span></span>
               .apis(RequestHandlerSelectors.any()) <span class="hljs-comment"><span class="hljs-comment"><span class="hljs-comment">// 對所有api進行監控</span></span>
               .paths(PathSelectors.any()) <span class="hljs-comment"><span class="hljs-comment"><span class="hljs-comment">// 對所有路徑進行監控</span></span>
               .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提供了一系列的預設屬性和便利方法。

4. 測試

   通過通路：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>           

5.   gradle:  

   compile('io.springfox:springfox-swagger-ui:2.2.2')

6. 再次通路：http://localhost:8080/your-app-root/swagger-ui.html 就可以看到可讀性較好的api文檔頁面。
7. 注意：
   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編寫

   4. SpringBoot 配置SwaggerUI 通路404的小坑。

      在學習SpringBoot建構Restful API的時候遇到了一個小坑，配置Swagger UI的時候無法通路。

      首先在自己的pom檔案中加入Swagger的依賴，如下所示：

      ?

      1 2 3 4 5 6 7 8 9 10 11

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

      然後在建立一個SwaggerConfig類：

      12 13 14 15 16 17 18 19 20 21 22

      Configuration @EnableSwagger2 public class SwaggerConfig { @Bean public Docket createRestApi() { return new Docket(DocumentationType.SWAGGER_2) .apiInfo(apiInfo()) .select() .apis(RequestHandlerSelectors.basePackage( "com.nightowl" )) .paths(PathSelectors.any()) .build(); } private ApiInfo apiInfo() { return new ApiInfoBuilder() .title( "NightOwl RESTful APIs" ) .description( "關注我 http://hwangfantasy.github.io/" ) .termsOfServiceUrl( "http://hwangfantasy.github.io/" ) .contact( "顔藝學長" ) .version( "1.0" ) .build(); } }

      最後在自己的Controller中加上一系列的API注解即可，其實不需要加上API注解也可以正常使用。 

      最後在localhost:8080/swagger-ui.html 通路即可看到swagger頁面了。

      但是關鍵來了，我第一次按照這樣的方法配置卻提示如下錯誤：

      Whitelabel Error Page This application has no explicit mapping for /error, so you are seeing this as a fallback. Thu Nov 24 19 : 57 : 13 CST 2016 There was an unexpected error (type=Not Found, status= 404 ). No message available

      但是我建立一個項目重新配置卻沒有任何問題，于是想到自己的項目中肯定有哪些配置與swagger沖突了， 

      最後發現在 application.properties 中把

      spring.resources. static -locations=classpath:/ static /

      這一行注釋掉即可通路了。

      以上就是本文的全部内容，希望對大家的學習有所幫助，也希望大家多多支援腳本之家。

      原文連結：http://blog.csdn.net/hwangfantasy/article/details/66542602

參考文獻

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

原文位址：https://www.cnblogs.com/h9527/p/5506956.htm