无意间从一个朋友那里听说swagger这个东西，经过他的展示，觉得挺不错的，主要功能就是方便、直观、漂亮的将后台所定义接口展示给客户端开发人员，而且还给后台开发人员节省了很多时间成本。
背景简介
缘何而来
在服务端开发过程中，开发人员往往会提供出来很多API接口供客户端开发人员使用，那么为了方便使用呢，开发人员会在开发接口的过程中同时维护一份文档，以说明每一个接口的访问方式、需要的参数、返回的结果等基本信息。但是这种传统的API书写方式很耗费时间，而且容易造成因为接口文档更新不及时导致的前后端双方交流成本增加的问题。
所谓工欲善其事，必先利其器。基于上述情况，诞生了许多API接口文档自动化生成工具，如Swagger、I/O Docs、apiary.io、Docco、Dexy、Doxygen、TurnAPI。今天重点要说的就是其中的Swagger。（宝宝再也不用担心接口文档的更新问题了）
我的全部
Swagger(The World's Most Popolar Framework for APIs)，is a simple yet powerful representation of your RESTful API. With the largest ecosystem of API tooling on the planet, thousands of developers are supporting Swagger in almost every modern programming language and deployment environment. With a Swagger-enabled API, you get interactive documentation, client SDK generation and discoverability.
Swagger是一个规范和完整的框架，用于生成、描述、调用和可视化Restful风格的Web服务。总体目标是使接口文档与服务端接口以同样的速度更新。文档的方法、参数和模型紧密集成到服务端的代码，允许API始终保持同步。Swagger让部署管理和使用功能强大的API变得如此简单。
像其他大的项目一样（如Spring），Swagger的下面也包含很多模块，那么这里主要涉及他的UI模块。
理论与实践相结合
本文基于Maven+SpringMVC4.3+Swagger环境，对swagger的使用进行介绍。
增加swagger相关jar包
<dependency>
<groupId>com.mangofactory</groupId>
<artifactId>swagger-springmvc</artifactId>
<version>1.0.2</version>
</dependency>
<dependency>
<groupId>com.mangofactory</groupId>
<artifactId>swagger-models</artifactId>
<version>1.0.2</version>
</dependency>
<dependency>
<groupId>com.wordnik</groupId>
<artifactId>swagger-annotations</artifactId>
<version>1.3.11</version>
</dependency>
自定义swagger基本配置
定义配置类SwaggerConfig文件（保证该文件在base-package扫描范围），如下所示。当然这不是必须的，如果没有自定义，swagger会使用缺省SwaggerSpringMvcPlugin，并且需要在配置文件中定义SpringSwaggerConfig的bean。
/**
+ Created by lxd on 2016/09/08.
*/
@Configuration//表明这是一个配置类，作用相当于xml配置文件
@EnableWebMvc//加载WebMvcConfigurationSupport基础配置类（其实就是sprintMvc的bean工厂）
@EnableSwagger//加载swagger的配置类
public class SwaggerConfig extends WebMvcConfigurerAdapter {
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(".*")
.useDefaultResponseMessages(false)
// .pathProvider(new GtPaths())
.apiVersion("0.1");
}
private ApiInfo apiInfo()
{
ApiInfo apiInfo = new ApiInfo(
"Swagger&SpringMVC整合实例",
"后台开发接口文档",
"本文档解决客户端与后台的连接问题",
"XXXXXX@163.com",
"做最好的自己",
"fasily.github.io");
return apiInfo;
}
@Override
public void configureDefaultServletHandling(
DefaultServletHandlerConfigurer configurer) {
configurer.enable();
}
class GtPaths extends SwaggerPathProvider {
@Override
protected String applicationPath() {
return "/restapi";
}
@Override
protected String getDocumentationPath() {
return "/restapi";
}
}
}
springMVC配置文件
不用像很多博文说的那样需要在配置文件中加入SpringSwaggerConfig 的Bean，下面是我的spingMVC的配置文件mvc-config.xml的配置情况。
<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:context="http://www.springframework.org/schema/context"
xmlns:mvc="http://www.springframework.org/schema/mvc"
xsi:schemaLocation="
http://www.springframework.org/schema/beans
http://www.springframework.org/schema/beans/spring-beans.xsd
http://www.springframework.org/schema/context
http://www.springframework.org/schema/context/spring-context.xsd
http://www.springframework.org/schema/mvc
http://www.springframework.org/schema/mvc/spring-mvc.xsd">
<mvc:annotation-driven />
<!-- 用于将对象转换为 JSON -->
<mvc:annotation-driven>
<mvc:message-converters>
<bean class="org.springframework.http.converter.StringHttpMessageConverter">
<property name="supportedMediaTypes">
<list>
<value>text/plain;charset=UTF-8</value>
<value>text/html;charset=UTF-8</value>
</list>
</property>
</bean>
<bean class="org.springframework.http.converter.json.MappingJackson2HttpMessageConverter">
<property name="supportedMediaTypes">
<list>
<value>application/json; charset=UTF-8</value>
<value>application/x-www-form-urlencoded; charset=UTF-8</value>
</list>
</property>
</bean>
</mvc:message-converters>
<bean id="handlerMapping" class="org.springframework.web.servlet.handler.BeanNameUrlHandlerMapping"/>
<bean
class="org.springframework.web.multipart.commons.CommonsMultipartResolver"
id="multipartResolver">
<property name="defaultEncoding" value="UTF-8" />
<property name="uploadTempDir" value="resources/attach/temp" />
</bean>
<bean id="viewResolver" class="org.springframework.web.servlet.view.InternalResourceViewResolver">
<property name="viewClass" value="org.springframework.web.servlet.view.JstlView"/>
<property name="prefix">
<value>/</value>
</property>
<property name="suffix">
<value>.jsp</value>
</property>
</bean>
</beans>
添加swagger相关注解
需要在接口文件（如controller中）添加swagger的相关注解配置，以达到更好的体验效果，以下是简单的示例。
@RestController
@RequestMapping("/*")
@Api(value = "/*", description = "用户相关接口", produces = MediaType.APPLICATION_JSON_VALUE)
public class UserActController extends BaseController {
Logger logger = LoggerFactory.getLogger(getClass());
// @Autowired
// UserService userService ;
@RequestMapping(value="user/loadUser.do",method = RequestMethod.GET)
@ApiOperation(notes = "user/loadUser.do",value = "获取用户", httpMethod = "GET", produces = MediaType.APPLICATION_JSON_VALUE)
public Result loadUser(
@ApiParam(value = "用户ID", required = true) @RequestParam Long userId
){
try {
User user = new User();
user.setMobile("13263859684");
user.setNickname("fasily");
return new Result<User>(true,user);
} catch( Exception e ) {
logger.error(e.getMessage());
return new Result(false,e.getMessage());
}
}
}
添加Swagger UI配置
在GitHub上下载SwaggerUI项目（https://github.com/swagger-api/swagger-ui） ，将dist下所有内容拷贝到本地项目webapp或其子目录下面，本人将这部分文件复制到了webapp下的swagger文件下。
然后将index.html中http://petstore.swagger.wordnik.com/v2/swagger.json 修改为 http://localhost:8080/{projectname}/api-docs。
web.xml
最后要确保dispatherServlet能够对 / 类型的请求进行拦截，如下。
预览效果
最后，访问http://localhost:8080/{projectName}/{所在文件夹}/index.html， 就可以看到最终的接口文档生成效果。如我这里是访问http://localhost:8080/swagger/index.html ，得到以下页面。
源码简介
这里对Swagger的源码做简单说明，有兴趣可以仔细查看源码。
- 数据准备--在源码中有一个监听类SwaggerPluginAdapter（实现了ApplicationListener的接口onApplicationEvent），这就是Swagger准备所有接口信息数据的入口。服务启动后就会通过该入口实现数据准备，最后所有前段API展示数据都会加载到SwaggerCache的bean对象中。
- 接口访问--有了所有的服务端接口信息数据之后，api-doc页面就可以通过发送请求获取到服务端的接口信息。这里所有的请求都会在DefaultSwaggerController中进行相应处理并返回需要数据。
结束语
- Swagger说白了就是一个API自动化生成工具，所以在将Swagger集成到SpringMVC时，需要首先确保SpringMVC接口可以正常访问。
- 就譬如我们解读一句话的含义时，需要将这句话放到指定的上下文中一样，本文关于Swagger的介绍并不一定会适用于所有场景（本文基于环境已在上述进行了说明），仅供大家参考，有问题或者异议可以给我留言。
- 本文的API书写方式并不属于流行的Restful风格，本人推荐大家尽量使用Restful这种接口定义风格。
参考资料
Swagger官网
API接口文档自动化生成工具推荐
Swagger文档
Swagger官方注解文档
参考文档
参考文档
