Swagger与SpringMVC项目整合
为了方便的管理项目中API接口，在网上找了好多关于API接口管理的资料，感觉目前最流行的莫过于Swagger了，功能强大，UI界面漂亮，并且支持在线测试等等，所以本人仔细研究了下Swagger的使用，下面就如何将Swagger与个人的SpringMVC项目进行整合做详细说明：
最终API管理界面：
详细步骤：
Step1:项目中引入相关jar包：
<properties>
<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
<version.spring>3.2.9.RELEASE</version.spring>
<version.jackson>2.4.4</version.jackson>
</properties>
<dependencies>
....
<dependency>
<groupId>com.mangofactory</groupId>
<artifactId>swagger-springmvc</artifactId>
<version>0.9.5</version>
</dependency>
<dependency>
<groupId>com.fasterxml.jackson.core</groupId>
<artifactId>jackson-annotations</artifactId>
<version>${version.jackson}</version>
</dependency>
<dependency>
<groupId>com.fasterxml.jackson.core</groupId>
<artifactId>jackson-databind</artifactId>
<version>${version.jackson}</version>
</dependency>
<dependency>
<groupId>com.fasterxml.jackson.core</groupId>
<artifactId>jackson-core</artifactId>
<version>${version.jackson}</version>
</dependency>
</dependencies>
Step2:添加自定义config文件
package com.spg.apidoc.common.configer;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
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;
/**
* 项目名称：apidoc
*
* @description:
* @author Wind-spg
* @create_time：2015年2月10日 上午10:27:51
* @version V1.0.0
*
*/
@Configuration
@EnableSwagger
// Loads the spring beans required by the framework
public class MySwaggerConfig
{
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(
"My Apps API Title",
"My Apps API Description",
"My Apps API terms of service",
"My Apps API Contact Email",
"My Apps API Licence Type",
"My Apps API License URL");
return apiInfo;
}
}
Step3:将此配置加入到Spring容器中，如下：
<bean class="com.spg.apidoc.common.configer.MySwaggerConfig" />
Step4:在代码中添加相关APIAnnotation，如下：
@ResponseBody
@RequestMapping(
value = "addUser", method = RequestMethod.POST, produces = "application/json; charset=utf-8")
@ApiOperation(value = "添加用户", httpMethod = "POST", response = BaseResultVo.class, notes = "add user")
public String addUser(@ApiParam(required = true, name = "postData", value = "用户信息json数据") @RequestParam(
value = "postData") String postData, HttpServletRequest request)
{
LOGGER.debug(String.format("at function, %s", postData));
if (null == postData || postData.isEmpty())
{
return super.buildFailedResultInfo(-1, "post data is empty!");
}
UserInfo user = JSON.parseObject(postData, UserInfo.class);
int result = userService.addUser(user);
return buildSuccessResultInfo(result);
}
说明：
其中@ApiOperation和@ApiParam为添加的API相关注解，个参数说明如下：
@ApiOperation(value = “接口说明”, httpMethod = “接口请求方式”, response = “接口返回参数类型”, notes = “接口发布说明”；其他参数可参考源码；
@ApiParam(required = “是否必须参数”, name = “参数名称”, value = “参数具体描述”
Step5：添加Swagger UI配置
在GitHub上下载SwaggerUI项目，将dist下所有内容拷贝到本地项目webapp下面，结果目录如下图所示：
Step6：修改index.html
将index.html中http://petstore.swagger.wordnik.com/v2/swagger.json修改为http://localhost:8080/{projectname}/api-docs
到此为止，所有配置完成，启动你的项目，访问http://localhost:8080/{projectName}/index.html即可看到如下所示页面：
项目最终demo可见个人GitHub
https://github.com/itboyspg/spg-code/tree/master/apidoc
参考：
https://github.com/martypitt/swagger-springmvc
https://github.com/swagger-api/swagger-ui
在开发者调用API之前对一些API说明的理解比较模糊，总想着能直接验证一下自己的理解就好了，而不是需要去项目写测试代码来验证自己的想法。即API文档应具备直接执行能力。Swagger就是这样的一个利器，Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法，参数和模型紧密集成到服务器端的代码，允许API来始终保持同步。Swagger 让部署管理和使用功能强大的API从未如此简单。
下面说一下如何为现有项目添加Swagger
首先添加对Swagger的依赖
<dependency>
<groupId>com.mangofactory</groupId>
<artifactId>swagger-springmvc</artifactId>
<version>0.9.1</version>
</dependency>
<dependency>
<groupId>com.wordnik</groupId>
<artifactId>swagger-core_2.10</artifactId>
<version>1.3.7</version>
</dependency>
<dependency>
<groupId>com.google.guava</groupId>
<artifactId>guava</artifactId>
<version>18.0</version>
</dependency>
<dependency>
<groupId>org.scala-lang</groupId>
<artifactId>scala-library</artifactId>
<version>2.10.0</version>
</dependency>import.springframework.beans.factory.annotation.Autowired;
import.springframework.context.annotation.Bean;
import.springframework.context.annotation.Configuration;
import.mangofactory.swagger.configuration.SpringSwaggerConfig;
import.mangofactory.swagger.plugin.EnableSwagger;
import.mangofactory.swagger.plugin.SwaggerSpringMvcPlugin;
import.wordnik.swagger.model.ApiInfo;
@Configuration
@EnableSwagger
publicclassMySwaggerConfig{
privateSpringSwaggerConfig;
/**
* Required to autowire SpringSwaggerConfig
*/
@Autowired
publicvoid(SpringSwaggerConfig){
this.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
publicSwaggerSpringMvcPlugin(){
SwaggerSpringMvcPlugin=newSwaggerSpringMvcPlugin(this.springSwaggerConfig)
.apiInfo(apiInfo())
.swaggerGroup("api-docs").build();
return;
}
privateApiInfo(){
ApiInfo=newApiInfo(
"tk API SPECIFICATION",
"This is the tk api specification,here you can dig into the details of api and do api testing as well.",
"",
"",
"",
"");
return;
}
}<mvc:annotation-driven/>
<beanid="apiDoc"class="com.tk.framework.rest.framework.swaggerconfig.MySwaggerConfig"/>
<!-- Enable scanning of spring @Configuration classes -->
<context:annotation-config/>
<!-- Enable the default documentation controller-->
<context:component-scanbase-package="com.mangofactory.swagger.controllers"/>
<!-- Pick up the bundled spring config-->
<context:component-scanbase-package="com.mangofactory.swagger.configuration"/>@RestController
@RequestMapping(value ="/1/users")
@Api(value ="User",="User service api",=1)
publicclassUserResourceV1extendsBaseResources
{
privatestaticfinalLogger=LoggerFactory.getLogger(UserResourceV1.class);
@Autowired
privateUserService;
@ResourceDescription(Resource="user",Operation="getUser")
@RequestMapping(value ="/{id}",=RequestMethod.GET)
@ApiOperation(httpMethod ="GET",="getUser",="get user by userId")
publicResponseModel(@ApiParam(value ="id for greeting",=true)@PathVariableString)throwsRestException
{
UserModel=null;
try
{
=.findById(id);
}
catch(Exception)
{
.error(e.getMessage());
thrownewRestException(e.getMessage());
}
ResponseModel=newResponseModel();
.setStatus(200);
.setResult(u);
return;
}}
@ApiModel(value="User")
@Entity
@Table(name ="user")
publicclassUserModel{
/**
* id
*/
@ApiModelProperty(required =true)
privateString;
/**
* 姓名
*/
@ApiModelProperty(required =true)
privateString;
/**
* 年龄
*/
@ApiModelProperty(required =true,="range[1,100]")
privateInteger;
/**
* 性别
*/
@ApiModelProperty(required =true,="F,M")
privateString;
@ApiModelProperty(required =true)
privateString;……
在Swagger Annotation中：
@API表示一个开放的API，可以通过description简要描述该API的功能。
在一个@API下，可有多个@ApiOperation，表示针对该API的CRUD操作。在ApiOperation Annotation中可以通过value，notes描述该操作的作用，response描述正常情况下该请求的返回对象类型。
在一个ApiOperation下，可以通过ApiResponses描述该API操作可能出现的异常情况。
@ApiParam用于描述该API操作接受的参数类型
接下来，我们把这些信息和Swagger UI集成，以非常美观，实用的方式把这些API信息展示出来。
首先，从github(https://github.com/wordnik/swagger-ui)上下载Swagger-UI, 把该项目dist目录下的内容拷贝到项目的webapp的目录下。
window.swaggerUi =newSwaggerUi({
:"/api/api-docs",
:"swagger-ui-container",
具有直接测试API的能力：
http://blog.163.com/xh_ding/blog/static/193903289201411592759809/