都說swagger是一個非常牛的自動生成介面文件的應用框架

一、Swagger是什麼？

   官方介紹：  Swagger是一個規範且完整的框架，提供描述、生產、消費和視覺化RESTful Web Service。

   專業角度：Swagger是由龐大工具集合支撐的形式化規範。這個集合涵蓋了從終端使用者介面、底層程式碼庫到商業API管理的方方面面。

二、匯入swagger需要的依賴

 在 POM.xml 中貼上如下依賴：

<!-- swagger API -->
		<dependency>
			<groupId>io.springfox</groupId>
			<artifactId>springfox-swagger2</artifactId>
			<version>2.6.0</version>
		</dependency>
		<dependency>
			<groupId>io.springfox</groupId>
			<artifactId>springfox-swagger-ui</artifactId>
			<version>2.6.0</version>
		</dependency>
		<!-- swagger-springmvc dependencies -->
		<dependency>
			<groupId>com.fasterxml.jackson.core</groupId>
			<artifactId>jackson-core</artifactId>
			<version>2.7.5</version>
		</dependency>
		<dependency>
			<groupId>com.fasterxml.jackson.core</groupId>
			<artifactId>jackson-annotations</artifactId>
			<version>2.7.5</version>
		</dependency>
		<dependency>
			<groupId>com.fasterxml.jackson.core</groupId>
			<artifactId>jackson-databind</artifactId>
			<version>2.7.5</version>
		</dependency>

		<dependency>
			<groupId>org.codehaus.jackson</groupId>
			<artifactId>jackson-mapper-asl</artifactId>
			<version>1.9.4</version>
		</dependency>

		<dependency>
			<groupId>org.codehaus.jackson</groupId>
			<artifactId>jackson-core-asl</artifactId>
			<version>1.9.4</version>
		</dependency>
 

三、在web中的src/main/java中建立一個swagger包將swagger2的配置類放入包中，如下圖：

下面是SwaggerConfig.java的程式碼：

package com.swagger.config;

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 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;

/**
* Swagger2配置類
* 在與spring boot整合時，放在與Application.java同級的目錄下。
* 通過@Configuration註解，讓Spring來載入該類配置。
* 再通過@EnableSwagger2註解來啟用Swagger2。
*/
@Configuration
@EnableWebMvc
@EnableSwagger2
@ComponentScan(basePackages="com.baidu.controller") //需要掃描的包路徑
public class SwaggerConfig {
    /**
     * 建立API應用
     * apiInfo() 增加API相關資訊
     * 通過select()函式返回一個ApiSelectorBuilder例項,用來控制哪些介面暴露給Swagger來展現，
     * 本例採用指定掃描的包路徑來定義指定要建立API的目錄。
     * 
     * @return
     */
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.any())
                .paths(PathSelectors.any())
                .build();
    }
    
    /*
   	 * "標題 title",
   	 * "描述 description", 
   	 * "termsOfServiceUrl", 
   	 * "聯絡郵箱 contact email",
   	 * "許可證的型別 license type", 
   	 * "許可證的連結 license url"
   	 */
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("Spring 中使用Swagger2構建RESTful APIs")
                .description("更多請關注http://www.baidu.com")
                .termsOfServiceUrl("http://www.baidu.com")
                .version("2.0")
                .build();
    }
}
 

四、下載swagger-ui，並將dist目錄中的檔案複製到webapp的目錄下

下載路徑：https://github.com/swagger-api/swagger-ui

swagger目錄：

複製到工程下的目錄並且更名為swagger：

做完這些操作之後，我們需要去配置下web.xml,在web.xml中貼入下面的程式碼：

<!-- springmvc配置 -->
	<!-- 解決post亂碼 -->
	<filter>
		<filter-name>CharacterEncodingFilter</filter-name>
		<filter-class>org.springframework.web.filter.CharacterEncodingFilter</filter-class>
		<init-param>
			<param-name>encoding</param-name>
			<param-value>utf-8</param-value>
		</init-param>
		<init-param>
			<param-name>forceEncoding</param-name>
			<param-value>true</param-value>
		</init-param>
	</filter>
	<filter-mapping>
		<filter-name>CharacterEncodingFilter</filter-name>
		<url-pattern>/*</url-pattern>
	</filter-mapping>

	<servlet>
		<servlet-name>springmvc</servlet-name>
		<servlet-class>org.springframework.web.servlet.DispatcherServlet</servlet-class>
		<!-- 指定載入的配置檔案 ，通過引數contextConfigLocation載入 -->
		<init-param>
			<param-name>contextConfigLocation</param-name>
			<param-value>classpath*:spring/springmvc.xml</param-value>
		</init-param>
	</servlet>

	<servlet-mapping>
		<servlet-name>springmvc</servlet-name>
		<url-pattern>*.do</url-pattern>
	</servlet-mapping>
	
	<servlet-mapping>
		<servlet-name>springmvc</servlet-name>
		<url-pattern>/</url-pattern>
	</servlet-mapping>
	
	<!-- Springmvc前端控制器掃描路徑增加“/v2/api-docs”，用於掃描Swagger的 /v2/api-docs，否則 /v2/api-docs無法生效。 -->
	<servlet-mapping>
    	<servlet-name>springmvc</servlet-name>
    	<url-pattern>/v2/api-docs</url-pattern>
	</servlet-mapping>
	
	<!-- spring配置 -->
	<!-- 載入spring容器 -->
	<context-param>
		<param-name>contextConfigLocation</param-name>
		<param-value>classpath*:spring/applicationContext*.xml</param-value>
	</context-param>
	<listener>
		<listener-class>org.springframework.web.context.ContextLoaderListener</listener-class>
	</listener>
 

最後，我們需要在springmvc.xml中，新增一句程式碼：

        <!--不攔截swagger下的資源 -->
	<mvc:resources location="/" mapping="/**" />

根據自己的佈局來調整不攔截的資源。

五、將dist中index.html中的url連結地址更改為：你所需要的url地址，例如：http://localhost:9000/v2/api-docs

六、訪問的圖片