SpringMVC+Swagger配置使用踩坑

SpringMVC+Swagger配置使用踩坑

背景

換了工做，從Android搬磚工成爲了產品經理，本覺得翻身農奴把歌唱，結果發現公司除了前端就只有我這個產品經理了。沒辦法，瞭解一下後端開發頂一陣子。接口寫完以後手寫接口文檔太痛苦了，因而搜索一番自動生成api文檔的工具，最後get到了神器Swagger和它的圖形化工具Swagger-UI。

前因都交代完了，從Android前端到Java後端的話語言方面沒什麼問題，框架使用的是SpringMVC，依賴注入和控制反轉有點相似Android的Dagger2項目，可是在配置方面有一些坑仍是踩了一遍，歸根結底是本身對SpringMVC的框架體系沒有理解，且是趕鴨子上架臨時上手一梭子。老項目，若是是新開項目可使用官方推薦的SpringBoot框架，配置使用更加簡單舒爽。

那麼先來波文檔回味一下什麼是SpringMVC：

• 官方文檔：Spring框架文檔
• Spring，Spring MVC及Spring Boot區別
• SpringMVC中文教程（極客學院）

瞭解完畢以後咱們經過SpringFox來添加配置Swagger。

若干大神寫文章講Swagger配置文檔的使用，我也來說講本身使用過程當中踩的坑吧，此文僅爲踩坑記錄，若有謬誤請指出。

最終配置及踩坑過程

maven庫導入

注意：我使用的是springfox 2.9.2最新版本，添加springfox自身便可，若是啓動項目時出現com/fasterxml/jackson/databind/ObjectMapper類找不到,請額外添加Jackson的依賴。(有教程說2.7.0版本的springfox有bug不建議使用，我未進行驗證)

<version.jackson>2.9.6</version.jackson>

<!-- jackson用於將springfox返回的文檔對象轉換成JSON字符串 -->
<dependency>
    <groupId>com.fasterxml.jackson.core</groupId>
    <artifactId>jackson-annotations</artifactId>
    <version>${version.jackson}</version>
</dependency>
<dependency>
    <groupId>com.fasterxml.jackson.core</groupId>
    <artifactId>jackson-databind</artifactId>
    <version>${version.jackson}</version>
</dependency>
<dependency>
    <groupId>com.fasterxml.jackson.core</groupId>
    <artifactId>jackson-core</artifactId>
    <version>${version.jackson}</version>
</dependency>

<!-- ========swagger2 api自動生成工具 start======== -->
<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>
<!-- ========swagger2 api自動生成工具 end======== -->

swagger java配置文件

注意：兩個類註解的添加。

import org.springframework.beans.factory.annotation.Value;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

/**
* Swagger配置文件。
* [Springfox官方集成文檔](http://springfox.github.io/springfox/docs/current/)
* [Swagger註解官方文檔](https://github.com/swagger-api/swagger-core/wiki/Annotations-1.5.X)
* <p>
* 配置注意事項：
* 1. swagger及swagger-ui的添加，注意版本
* 2. 該config文件的註解添加，@Configuration與@EnableSwagger2爲必須添加
* 3. 配置servlet-mapping爲"/"，由於會生成靜態文件，所以須要注意路徑穿透
*
* @author sanchi
*/
@Configuration
@EnableSwagger2
public class SwaggerConfig {

    /**
    * 根據配置讀取是否開啓swagger文檔，針對測試與生產環境採用不一樣的配置
    */
    @Value("${swagger.enable}")
    private boolean isSwaggerEnable;

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("sanchi")
                .enable(isSwaggerEnable)
                .apiInfo(apiInfo()).select()
                // 對全部該包下的Api進行監控，若是想要監控全部的話能夠改爲any()
                .apis(RequestHandlerSelectors.basePackage("com.sanchi.test"))
                // 對全部路徑進行掃描
                .paths(PathSelectors.any())
                .build();
    }

    /**
    * @return 生成文檔說明信息
    */
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("Sanchi test API文檔")
                .description("接口文檔")
                .termsOfServiceUrl("http://sanchips.github.io")
                .version("1.0.0").build();
    }
}

SpringMVC配置

檢查dispatcherServlet的mapping映射規則，是否爲轉發全部的請求。也是我本次配置最坑的地方，由於是個老項目，映射處只配置了對.php和.do的轉發，沒有配置爲/，致使swagger-ui.html根本訪問不到，訪問對應路徑時循環彈窗提示url路徑不對。打開頁面瀏覽器控制檯時發現有報錯：swagger-resources/configuration/ui 404 (not found)，對於這個十分困惑，檢索了好多文章都沒有找到答案，直到找到這篇文章對於servlet靜態資源穿透的說明才恍然大悟，老手們應該不會犯這麼低級的錯誤吧😂

<!-- servlet處理全部請求，配合<mvc:default-servlet-handler />進行靜態資源轉發 -->
<servlet-mapping>
    <servlet-name>dispatcherServlet</servlet-name>
    <url-pattern>/</url-pattern>
</servlet-mapping>

其餘一些配置內容，這部份內容：

<!-- 靜態資源請求轉發 -->
<mvc:default-servlet-handler/>
<!-- 啓動註解 -->
<mvc:annotation-driven/>
<!-- 自動注入，使系統可以識別相應的註解，使用<context:component-scan/>手動掃描後能夠省略該配置 -->
<context:annotation-config/>
<!-- 配置全局使用的k-v文件路徑，添加控制參數，區分測試與正式環境以爲是否啓用swagger api文檔 -->
<context:property-placeholder location="classpath*:context-sanchi.properties" file-encoding="UTF-8"/>

<!-- 添加Swagger2的java config做爲SpringMVC的bean -->
<bean class="com.sanchi.test.config.SwaggerConfig"/>

context-sanchi.properties文件中添加控制參數：

# ======swagger是否啓用配置字段======
swagger.enable=true

區分測試與正式環境

上面也提到了區分測試與正式環境以爲是否啓用swagger api文檔，有人提到了根據正式或者測試環境是否引用<bean class="com.sanchi.test.config.SwaggerConfig"/>，以爲這種方式不太友好，找到這篇文章，發現swagger在配置的時候有提供一個enable的方法，因而使用properties參數配置的方式，見上面內容☝

至此，運行項目，打開swagger-ui頁面，熟悉的界面出現，列出了全部controller下的接口信息，按照步驟添加api註解註釋便可。配置結束，前期的坑也踩完了。

PS：發現一個彩蛋，SwaggerConfig文件添加@EnableWebMvc註解以後打開的ui界面跟不加不一樣，暫未作深究😛