SpringMVC整合SwaggerUI

文章目錄

SpringMVC整合SwaggerUI
- 概念介紹
- 相關資源下載下傳
- 編寫整合代碼
- - index.html檔案修改
  - maven中引入依賴
  - springmvc配置檔案中配置資源路徑
  - 編寫swagger配置檔案
- 效果展示
- 整合時可能出現的異常
- - 問題分析
  - 問題解決
- 總結
- 參考資料

網上介紹Swagger整合的文章很多，但都是東拼西湊，抄來抄去，講不清楚重點。本文的目的就是希望那些從來沒有接觸過Swagger的朋友能按照本文的步驟快速實作SpringMVC和SwaggerUI的整合，在界面上看到自己的API介紹。如果想深入研究Swagger，本文也附上了相關連結供參考。最終效果如下所示。

SpringMVC整合SwaggerUISpringMVC整合SwaggerUI

概念介紹

初接觸Swagger的朋友一定會被一堆專業名詞搞得暈頭轉向，什麼SpringFox、Swagger、SwaggerUI、SwaggerEditor、SwaggerCodegen、SwaggerInspector等。想做整合，了解下面三個概念即可，想全部了解，可以參考文末連結1，有詳細介紹。

Swagger: 是一個規範和完整的架構，用于生成、描述、調用和可視化RESTful風格的Web服務。簡單說就是一套生成文檔的架構，要想将其整合進自身的項目，需要實作相關的接口。
SwaggerUI: 一套前端界面，用于發送請求給背景的Controller，讀取背景傳回的JSON資訊并渲染成相關漂亮的頁面。
SpringFox: Swagger規範的Spring實作，第三方提供更新和維護。

了解了上述概念，本文要做的事情也就清楚了：利用第三方提供的SpringFox将自身項目中的RESTful API在SwaggerUI中顯示出來。

編寫整合代碼

接下來我們展示如何整合

2.x

版本的swagger-ui。

index.html檔案修改

對于基于SpringMVC的web項目來說，毫無疑問要把上述資源放到

webapp

目錄下。接下來打開index.html檔案，需要對文檔做幾處修改，如下圖所示。

SpringMVC整合SwaggerUISpringMVC整合SwaggerUI

圖中第一個紅框放開了兩段注解，目的是讓swagger-ui的顯示語言為中文。第二個紅框是根據自身項目的名稱來指定文檔的通路路徑。

需要注意的是，通常的通路路徑是

/項目名/v2/api-docs

，項目名可變，其他固定。為什麼其他部分固定呢？因為springfox中路徑的預設值就是

/項目名/v2/api-docs

。需要變更的話還得自己寫配置檔案，比較麻煩，感興趣的朋友可參考文末連結2。

圖中在通路url中新增了

/rest

，這是因為我的項目中所有RESTful API都在該路徑下。這裡所新增的路徑在後面swagger的配置檔案中都需要加上。

maven中引入依賴

上文已對springfox的概念做了介紹，我們的springmvc項目中需要使用該工具，首先得添加依賴項。

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.4.0</version>
</dependency>
<dependency>
    <groupId>com.google.guava</groupId>
    <artifactId>guava</artifactId>
    <version>18.0</version>
</dependency>

不同版本的springfox的依賴項最低版本也不一樣，需要自行修改。

springmvc配置檔案中配置資源路徑

資源路徑配置沒什麼好說的，原理和配置js、css等其他資源檔案一樣。

<!-- Swagger支援（暫時注釋掉提高平台性能，需要此功能，可以放開注釋）-->
<context:component-scan base-package="springfox"/>
<bean class="org.test.core.swagger.SwaggerConfig"/>
<mvc:resources mapping="/swagger/**" location="/swagger/"/>

編寫swagger配置檔案

swagger配置檔案的作用是為了告訴springmvc在啟動的時候啟用springfox，并到配置的路徑下掃描RESTful API。下面我們建立配置類，

SwaggerConfig.java

。

@Configuration
@EnableSwagger2
public class SwaggerConfig {
    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .pathMapping("/rest/")//對請求的路徑增加rest字首
                .globalOperationParameters(setHeaderToken())
                .select()
                .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class)) //隻過濾包含有ApiOperation注解的方法
                .paths(PathSelectors.any()) //對所有的路徑進行監控
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("文檔标題")
                .description("文檔概述。")
                .contact(new Contact("公司名", "公司網址", "聯系人郵箱"))
                .version("版本号")
                .build();
    }

    private List<Parameter> setHeaderToken() {
        ParameterBuilder tokenPar = new ParameterBuilder();
        List<Parameter> pars = new ArrayList<>();
        tokenPar.name("X-AUTH-TOKEN").description("token").modelRef(new ModelRef("string")).parameterType("header").required(false).build();
        pars.add(tokenPar.build());
        return pars;
    }
}

上述配置類具有通用性，該填寫的内容也已注明。需要注意的是，如果我們希望通路每個API的時候都需要帶TOKEN，那麼就需要配置

setHeaderToken()

，這裡配置的TOKEN資訊會顯示在每個API的第一個參數上。反之則不用調用。

如果想對springfox的原理深入了解，可參考文末連結3。

效果展示

根據上述配置類，swagger-ui上顯示的内容如下：

SpringMVC整合SwaggerUISpringMVC整合SwaggerUI

如果配置了通路TOKEN，每個API的效果如下，一一對照上述的配置就知道

setHeaderToken()

方法中每部分的作用了。

SpringMVC整合SwaggerUISpringMVC整合SwaggerUI

整合時可能出現的異常

如果項目能編譯通過，但是啟動時報下述異常，可能就是SpringMVC中相關配置缺失了。

Error creating bean with name ‘documentationPluginsBootstrapper’ defined in URL…
Error creating bean with name ‘webMvcRequestHandlerProvider’ defined in URL…
No qualifying bean of type [org.springframework.web.servlet.mvc.method.RequestMappingInfoHandlerMapping] found for dependency…

問題分析

上述嵌套異常出現的根本原因是沒有找到

RequestMappingInfoHandlerMapping

的實作類，無法

Autowired

。

在springmvc中源碼找到該類，發現它是一個抽象類。

Ctrl+T

一下，發現該類的實作為

RequestMappingHandlerMapping

。是以問題原因就是沒有在springmvc.xml的配置檔案中配置該bean。

問題解決

springmvc.xml中添加下述配置即可解決問題。因為添加了

RequestMappingHandlerMapping

就得添加

RequestMappingHandlerAdapter

，否則會報找不到擴充卡的錯誤。

<!-- 避免IE執行AJAX時,傳回JSON出現下載下傳檔案 -->
<bean id="mappingJacksonHttpMessageConverter" class="org.springframework.http.converter.json.MappingJacksonHttpMessageConverter">
    <property name="supportedMediaTypes">
        <list>
            <value>text/html;charset=UTF-8</value>
            <value>text/json;charset=UTF-8</value>
            <value>application/json;charset=UTF-8</value>
        </list>
    </property>
</bean>
<!-- ResponseBody傳回字元串帶雙引号解決 -->
<bean id="stringHttpMessageConverter" class="org.springframework.http.converter.StringHttpMessageConverter">
    <constructor-arg value="UTF-8" index="0"/>
    <property name="supportedMediaTypes">
        <list>
            <value>text/plain;charset=UTF-8</value>
        </list>
    </property>
</bean>
<!-- 注冊handler method和request的mapping關系。  -->
<bean class="org.springframework.web.servlet.mvc.method.annotation.RequestMappingHandlerMapping"/>
<!-- 啟動Spring MVC的注解功能，完成請求和注解POJO的映射， 配置一個基于注解的定制的WebBindingInitializer，解決日期轉換問題，方法級别的處理器映射 -->
<bean class="org.springframework.web.servlet.mvc.method.annotation.RequestMappingHandlerAdapter">
    <property name="cacheSeconds" value="0"/>
    <property name="messageConverters">
        <list>
            <ref bean="stringHttpMessageConverter"/> <!--先進行string轉換-->
            <ref bean="mappingJacksonHttpMessageConverter"/><!-- json轉換器 -->
        </list>
    </property>
</bean>

總結

本文先對swagger的相關概念進行了介紹，接着詳細介紹了整合步驟，并對實際踩過的坑進行了剖析。詳細隻要按照本文的步驟，整個自己項目的swagger-ui是件很容易的事情。

參考資料

Swagger介紹及使用
Spring boot中使用springfox來生成Swagger Specification小結
API管理工具Swagger介紹及Springfox原理分析

SpringMVC整合SwaggerUISpringMVC整合SwaggerUI

SpringMVC整合SwaggerUI

文章目錄

概念介紹

相關資源下載下傳

編寫整合代碼

index.html檔案修改

maven中引入依賴

springmvc配置檔案中配置資源路徑

編寫swagger配置檔案

效果展示

整合時可能出現的異常

問題分析

問題解決

總結

參考資料

繼續閱讀

【Spring】解決SpringTask定時執行兩次問題

springMVC實作JSON互動

配置springmvc傳回json格式資料

springmvc傳回json資料（零配置方式）

jquery,ajax,jsonp例子+springmvc背景

SpringMVC(六) | 前後端互動之ajax與jsonjsonajax

SpringMVC之ajax異步互動

Spring MVC 自學雜記（五） -- SpringMVC與前台的json資料互動

SpringMVC ----Json的簡單互動處理Json的介紹JSON 和 JavaScript 對象互轉Controller傳回JSON資料

SpringMvc與前端互動的資料轉遞（ajax）一、text類型資料二、json類型資料

springMvc如何和前端頁面互動，傳輸json資料springMvc和前端傳輸資料

spingmvc 檔案上傳一、單檔案上傳二、多檔案上傳

spingmvc實作附件單個和打包下載下傳

SpringMVC傳回json資料的三種方式

SpringMVC常見注釋的簡述

SSM架構（二）------------表現層的SpringMVC