Springmvc集成Swagger 简单快速

1.Swagger概述

Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法，参数和模型紧密集成到服务器端的代码，允许API来始终保持同步。

主要作用：接口的文档在线自动生成；功能测试。

2.maven添加依赖

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

3.创建Swagger2配置类

/**
* Swagger2配置类
* 在与spring boot集成时，放在与Application.java同级的目录下。
* 通过@Configuration注解，让Spring来加载该类配置。
* 再通过@EnableSwagger2注解来启用Swagger2。
*/
@Configuration
@EnableWebMvc
@EnableSwagger2
@ComponentScan(basePackages="com.baidu.dept.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();
    }
}

如上代码所示，通过createRestApi函数创建Docket的Bean之后，apiInfo()用来创建该Api的基本信息（这些基本信息会展现在文档页面中）。

4.静态资源文件的配置

https://github.com/swagger-api/swagger-ui/tree/v2.2.1

进入github 下载源码，下载完成后，解压文件。在你项目的webapp目录下，创建一个文件夹，命名为swagger（当然，你也可以用其他的名字命名），然后去刚才解压的文件中找到dist，将dist文件夹里面的所有文件拷贝到swagger下(注意版本最高下载2.2.10才支持springmvc)；

打开index.html将url改成自己的url

在springmvc.xml文件中加入

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

5.修改web.xml文件，配置MVC

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

5.测试Controller类

/**
 * 一个用来测试swagger注解的控制器
 * 注意@ApiImplicitParam的使用会影响程序运行，如果使用不当可能造成控制器收不到消息
 * 
 * @author admin
 */

@Controller
@RequestMapping("/dept")
@Api("TestController")    //用在类上，说明该类的作用。
public class TbDeptController {
	@Reference
	private TbDeptService tbDeptService;
	
	
	/*
	 * @ApiOperation(value = "接口说明", httpMethod ="接口请求方式", response ="接口返回参数类型", notes ="接口发布说明"
	 * 
	 * @ApiParam(required = "是否必须参数", name ="参数名称", value ="参数具体描述"
	 */
	
	@RequestMapping("/findList.do")
	@ResponseBody
	@ApiOperation(value = "查询所有部门信息", httpMethod ="GET", produces=MediaType.APPLICATION_JSON_UTF8_VALUE, notes ="获取LISt")
	public List<TbDept> findList() {
		return tbDeptService.findList();
	}
	
	
	
}

6.接口管理页面的访问

访问：swagger目录下的index.html

看到这个界面就OK了。你也可以测测你的接口。

扫描二维码关注公众号，回复： 5799874 查看本文章