Spring MVC学习总结（9）——Spring MVC整合swagger自动生成api接口文档

Swagger 号称：世界最流行的API框架，官网：http://swagger.io/，Swagger
是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法，参数和模型紧密集成到服务器端的代码，允许API来始终保持同步。Swagger 让部署管理和使用功能强大的API从未如此简单。

使用工具：eclipse，jdk7，maven，spring

使用方法：

首先你得有自己的一个能访问的api代码，一个简单的demo就可以，然后我们开始添加代码

1.maven依赖：

<!-- swagger-springmvc dependencies -->

<dependency>

<groupId>com.google.guava</groupId>

<artifactId>guava</artifactId>

<version>15.0</version>

</dependency>

<dependency>

<groupId>com.fasterxml.jackson.core</groupId>

<artifactId>jackson-annotations</artifactId>

<version>2.4.4</version>

</dependency>

<dependency>

<groupId>com.fasterxml.jackson.core</groupId>

<artifactId>jackson-databind</artifactId>

<version>2.4.4</version>

</dependency>

<dependency>

<groupId>com.fasterxml.jackson.core</groupId>

<artifactId>jackson-core</artifactId>

<version>2.4.4</version>

</dependency>

<dependency>

<groupId>com.fasterxml</groupId>

<artifactId>classmate</artifactId>

<version>1.1.0</version>

</dependency>

<!-- CORS配置，为了让别的机器访问本机的swagger接口文档服务 -->

<dependency>

<groupId>com.thetransactioncompany</groupId>

<artifactId>cors-filter</artifactId>

<version>2.5</version>

2.我们在代码中添加SwaggerConfig配置类：

import org.springframework.beans.factory.annotation.Autowired;

import org.springframework.context.annotation.Bean;

import org.springframework.context.annotation.Configuration;

import org.springframework.web.servlet.config.annotation.EnableWebMvc;

import com.mangofactory.swagger.configuration.SpringSwaggerConfig;

import com.mangofactory.swagger.models.dto.ApiInfo;

import com.mangofactory.swagger.plugin.EnableSwagger;

import com.mangofactory.swagger.plugin.SwaggerSpringMvcPlugin;

@Configuration

@EnableSwagger

@EnableWebMvc

public class SwaggerConfig {

private SpringSwaggerConfig springSwaggerConfig;

/**

* Required to autowire SpringSwaggerConfig

*/

@Autowired

public void setSpringSwaggerConfig(SpringSwaggerConfig springSwaggerConfig) {

this.springSwaggerConfig = springSwaggerConfig;

}

/**

* Every SwaggerSpringMvcPlugin bean is picked up by the swagger-mvc

* framework - allowing for multiple swagger groups i.e. same code base

* multiple swagger resource listings.

*/

@Bean

public SwaggerSpringMvcPlugin customImplementation() {

return new SwaggerSpringMvcPlugin(this.springSwaggerConfig).apiInfo(apiInfo()).includePatterns(".*?");

}

private ApiInfo apiInfo() {

ApiInfo apiInfo = new ApiInfo(

"ums接口文档",

"这里是所有的ums接口，里边含有说明，请自行测试",

"My Apps API terms of service",

"My Apps API Contact Email",

"My Apps API Licence Type",

"My Apps API License URL");

return apiInfo;

}

}

这里得有一个注意的地方， @EnableWebMvc注解，在网上的大部分代码中都没有这个注解，小编做的时候也遇到了很大的麻烦，会报SwaggerConfig类不能自动装载，加上了这个就好了，具体用法大家想了解的自行查找。

3.springMVC配置文件中加上这段代码：

<!-- swagger测试 :注入SpringSwaggerConfig-->

<beanclass="com.mangofactory.swagger.configuration.SpringSwaggerConfig"/>

4.添加测试类：

import org.springframework.stereotype.Controller;

import org.springframework.web.bind.annotation.PathVariable;

import org.springframework.web.bind.annotation.RequestMapping;

import org.springframework.web.bind.annotation.RequestMethod;

import org.springframework.web.bind.annotation.ResponseBody;

import com.wordnik.swagger.annotations.ApiOperation;

import com.wordnik.swagger.annotations.ApiParam;

@RequestMapping(value = "/rs/swagger")

@Controller

public class SwaggerTestController {

/**

* 根据用户名获取用户对象

* @param name

* @return

*/

@RequestMapping(value="/name/{name}", method = RequestMethod.GET)

@ResponseBody

@ApiOperation(value = "根据用户名获", httpMethod = "GET", response = UserDTO.class, notes = "根据用户名获取用户对象")

public UserDTO getUserByName(@ApiParam(required = true, name = "name", value = "用户名") @PathVariable String name) throws Exception{

UserDTO ucUser = new UserDTO();

ucUser.setLoginName("测试账号");

return ucUser;

}

/**

* 根据用户名获取用户对象

* @param name

* @return

*/

@RequestMapping(value="/age/{age}", method = RequestMethod.GET)

@ResponseBody

@ApiOperation(value = "根据", httpMethod = "GET", response = UserDTO.class, notes = "根据用户名获取用户对象")

public UserDTO getUserByaa(@ApiParam(required = true, name = "name", value = "用户名") @PathVariable String name) throws Exception{

UserDTO ucUser = new UserDTO();

ucUser.setLoginName("测试账号");

return ucUser;

}

}

UserDTO这个类大家可自行定义。

经过这几步之后你就可以看到返回的数据了，但是是json的格式，下面我们来配置swagger：

1. 大家首先去官网下载压缩包，解压之后将里边的dist文件直接复制到项目中的src下边的main下的webapp中，改名为apidocs（为了直观），之后的效果是这样的：

   

2.打开apidocs中的index.html文件，搜索http://petstore.swagger.io/v2/swagger.json，修改格式为http://ip:端口/项目名/api-docs

3.tomcat:run启动tomcat项目，或者放到本地的tomcat中，在浏览器中输入访问地址即可访问到swagger主页：我的主页是这样的（汉化之后）：

4.这时候遇到了一个问题：本机可以访问但是别的机器不能访问，这样我们就失去了这个技术的初衷，别的机器访问的时候回报错：原因是cors跨域限制，这时候我们在web.xml中假如一段代码即可：

<!-- cors配置 -->

<filter>

<filter-name>CORS</filter-name>

<filter-class>com.thetransactioncompany.cors.CORSFilter</filter-class>

<init-param>

<param-name>cors.allowOrigin</param-name>

<param-value>*</param-value>

</init-param>

<init-param>

<param-name>cors.supportedMethods</param-name>

<param-value>GET, POST, HEAD, PUT, DELETE</param-value>

</init-param>

<init-param>

<param-name>cors.supportedHeaders</param-name>

<param-value>Accept, Origin, X-Requested-With, Content-Type, Last-Modified</param-value>

</init-param>

<init-param>

<param-name>cors.exposedHeaders</param-name>

<param-value>Set-Cookie</param-value>

</init-param>

<init-param>

<param-name>cors.supportsCredentials</param-name>

<param-value>true</param-value>

</init-param>

</filter>

<filter-mapping>

<filter-name>CORS</filter-name>

<url-pattern>/*</url-pattern>

</filter-mapping>