Maven+SpringMVC+Swagger 整合完整流程

都说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

六、访问的图片

Maven+SpringMVC+Swagger 整合完整流程

猜你喜欢