03、Swagger2和Springmvc整合詳細記錄（爬坑記錄）

時間	內容	備註
2018年6月18日	基本使用	spirngmvc整合swagger2

開始之前這個系列博文基本是，在項目的使用中一些模塊的內容記錄，但是後期逐漸優化，不單單是整合內容。

swagger簡介

1、swagger主要提供了三個功能:

• Swagger Editor: Swagger提供的一個編輯器，用來通過Swagger提供的特定的YAML語法來編寫API文檔
• Swagger Codegen: 代碼生成器
• Swagger UI: YAML語法定義我們的RESTful API，然後它會自動生成一篇排版優美的API文檔，並且提供實時預覽。

spirngmv 整合swagger

其實這個整合例子甚多，可以選擇的使用。

推薦：官方的說明文檔，雖是英文但是各個配置含義說明的很清楚建議使用，後期的優化內容根據這個執行的。

導入基本步驟:

1、修改pom.xml；添加如下swagger的依賴

<!-- 構建Restful API -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.4.0</version>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.4.0</version>
</dependency>

2、添加如下的配置類
注意如下不是必要的步驟(swagger會使用默認配置)

package com.weir.utils;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.ComponentScan;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.EnableWebMvc;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurationSupport;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration
@EnableSwagger2
@EnableWebMvc
@ComponentScan(basePackages ="com.weir")
class ApiConfig extends WebMvcConfigurationSupport {
    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.weir"))
                .paths(PathSelectors.any())
                .build()
                .apiInfo(apiInfo());
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("接口列表 v1.1.0") // 任意，請稍微規範點
                .description("接口測試") // 任意，請稍微規範點
                .termsOfServiceUrl("http://localhost:8080/swagger-ui.html") // 將“url”換成自己的ip:port
                .version("1.1.0")
                .build();
    }
}

3、修改springmvc.xml文件；添加關於swagger的配置，內容如下:

<mvc:default-servlet-handler />
<!-- 配置Swagger相關靜態資源 -->
<mvc:resources location="classpath:/META-INF/resources/" mapping="swagger-ui.html"/>
<mvc:resources location="classpath:/META-INF/resources/webjars/" mapping="/webjars/**"/>
<!-- 添加掃描配置類 -->
<bean class="com.weir.utils.ApiConfig" />

4、代碼中的使用：

@RequestMapping(value = "/login")
@ApiOperation(value = "用戶登錄", notes = "用戶登錄操作")
@ApiImplicitParam(name = "id", value = "用戶ID", required = true, dataType = "Long")
@ResponseBody
public ServerResponse<User> login(String userName, String password, HttpSession session){

    ServerResponse<User> response = userService.login (userName, password);
    if (response.isSuccess ()){
        session.setAttribute ("user",response);
    }
    return response;
}

5、運行顯示

導入遇到問題記錄：

最重要的內容：（自己爬坑的內容）【一定要注意】

1、控制檯報錯內容：Getting HTTP 404 error on /swagger-ui.html but other swagger endpoint works

攔截路徑改爲/，不要配置成後綴的，例如：/*.do等，這會導致，wagger-ui.html頁面被攔截，無法加載。

<!-- dispatcherServlet -->
<servlet>
<servlet-name>dispatcherServlet</servlet-name>
<servlet-class>org.springframework.web.servlet.DispatcherServlet</servlet-class>
<init-param>
  <param-name>contextConfigLocation</param-name>
  <param-value>classpath:springmvc.xml</param-value>
</init-param>
</servlet>
<servlet-mapping>
<servlet-name>dispatcherServlet</servlet-name>
<url-pattern>/</url-pattern>
</servlet-mapping>

當然如果你要配置成帶有後綴的也是可以的，請參考如下內容：

• 解決的關鍵參考頁面 [github的issue]
• 關於配置成爲的後綴的方式解決官方文檔

總結：

• 他人博文只是具有參考意義，儘量參考官方說明文檔，弄懂原理是關鍵
• 推薦官方文檔，中文文檔和博客參差不齊
• 不要位畏懼英文文檔和資料