今天给大家介绍一款工具，这个工具眼下可预见的优点是：自己主动维护最新的接口文档。

我们都知道，接口文档是非常重要的，可是随着代码的不断更新，文档却非常难持续跟着更新，今天要介绍的工具，完美的攻克了这个问题。

并且。对于要使用我们接口的人来说，不须要在给他提供文档，告诉他地址。一目了然。

近期项目中一直有跟接口打交道，恰好又接触到了一个新的接口工具，拿出来跟大家分享一下。

关于REST接口，我在上篇文章中已经有介绍。这里来说一下怎样配合SwaggerUI搭建RestFul API 的可视化界面。终于要达到的效果是这种：

它能够支持Rest的全部提交方式，如POST,GET,PUT,DELETE等。

这里能够看到我们的方法凝视，须要的參数。參数的类型和凝视。返回值的类型凝视等信息，最重要的，我们这里能够直接对REST接口測试。

接下来。我们一起開始逐步实现如图的效果

第一步：

首先。引入依赖的jar包

	
         	
         		
          
           com.mangofactory
          		
          
           swagger-springmvc
          		
          
           0.9.5
          	
         	
                     
          
           com.fasterxml.jackson.core
                      
          
           jackson-annotations
                      
          
           2.4.4
                  
                 
                     
          
           com.fasterxml.jackson.core
                      
          
           jackson-databind
                      
          
           2.4.4
                  
                 
                     
          
           com.fasterxml.jackson.core
                      
          
           jackson-core
                      
          
           2.4.4
                  
         

第二步，创建swagger配置文件类。基本不用改，仅仅须要改动要匹配的方法路径就可以。

package com.gochina.mis.util;import org.springframework.beans.factory.annotation.Autowired;import org.springframework.context.annotation.Bean;import org.springframework.context.annotation.ComponentScan;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;@Configuration@EnableSwaggerpublic class SwaggerConfig {	private SpringSwaggerConfig springSwaggerConfig;	@Autowired	public void setSpringSwaggerConfig(SpringSwaggerConfig springSwaggerConfig) {		this.springSwaggerConfig = springSwaggerConfig;	}	@Bean    public SwaggerSpringMvcPlugin customImplementation()    {

return new SwaggerSpringMvcPlugin(this.springSwaggerConfig).apiInfo(apiInfo()).includePatterns("/album/*");//这里是支持正则匹配的。仅仅有这里配置了才干够在页面看到。    }	private ApiInfo apiInfo() {		ApiInfo apiInfo = new ApiInfo(null,null,null,null,null,null);		return apiInfo;	}}

第三步：

把配置文件类增加spring容器

到这里，我们后台的环境代码就完毕了，接着，加入SwaggerUI提供的js界面

下载swagger-ui

https://github.com/swagger-api/swagger-ui

将dist下的文件放入webapp下

配置mvc：resource。防止spring拦截。

将index.html中的

http://petstore.swagger.wordnik.com/v2/swagger.json

改动为http://localhost:8080/{projectname}/api-docs

到此，完毕了全部的基本配置，接下来，须要对每一个接口加入注解。

以下来个实例

接口类

package com.gochina.mis.api;import org.slf4j.Logger;import org.slf4j.LoggerFactory;import org.springframework.beans.BeanUtils;import org.springframework.beans.factory.annotation.Autowired;import org.springframework.stereotype.Controller;import org.springframework.web.bind.annotation.ModelAttribute;import org.springframework.web.bind.annotation.RequestMapping;import org.springframework.web.bind.annotation.RequestMethod;import org.springframework.web.bind.annotation.ResponseBody;import com.gochina.mis.bean.Album;import com.gochina.mis.bean.ResultPo;import com.gochina.mis.service.AlbumService;import com.gochina.mis.util.JsonUtil;import com.gochina.mis.util.StringUtil;import com.gochina.mis.vo.BaseVo;import com.gochina.mis.vo.RequestAlbumVo;import com.wordnik.swagger.annotations.Api;import com.wordnik.swagger.annotations.ApiOperation;@Controllerpublic class AlbumAction {	private static Logger logger = LoggerFactory.getLogger(AlbumAction.class);		@Autowired	private AlbumService albumService;		@ResponseBody	@RequestMapping(value="album", method = RequestMethod.POST,produces = "application/json;charset=utf-8")	@ApiOperation(value="第三方加入专辑", httpMethod ="POST", response=BaseVo.class, notes ="第三方加入专辑")	public String postAlbum(@ModelAttribute("requestAlbumVo")RequestAlbumVo requestAlbumVo){		BaseVo result = new BaseVo();		Album album = new Album();		if (requestAlbumVo!=null) {			logger.info("传入參数：requestAlbumVo:{}",JsonUtil.beanToJson(requestAlbumVo));			try {				BeanUtils.copyProperties(requestAlbumVo, album);				result=albumService.save(album);			} catch (Exception e) {				e.printStackTrace();				result.setSuccess(false);				result.setMsg("加入专辑失败！

"); logger.error("加入专辑失败传入參数：requestAlbumVo:{},错误信息为：{}",JsonUtil.beanToJson(requestAlbumVo),e.getMessage()); } }else { result.setSuccess(false); result.setMsg("參数不合法！"); } logger.info("传入參数：requestAlbumVo:{},返回结果为：{}",JsonUtil.beanToJson(requestAlbumVo),JsonUtil.beanToJson(result)); return JsonUtil.beanToJson(result); } }

我们能够看到，这里使用SpringMVC,请求參数传入的是实体类。对于传入參数的注解，就放到了实体中

请求參数实体

package com.gochina.mis.vo;import com.wordnik.swagger.annotations.ApiModelProperty;public class RequestAlbumVo {		@ApiModelProperty(value = "专辑名称", required = true)	private String name;		@ApiModelProperty(value = "第三方专辑Id", required = true)	private String thirdAlbumId;//第三方专辑Id		@ApiModelProperty(value = "第三方专辑Id", required = true)	private String thirdSystemId;//第三方系统Id		@ApiModelProperty(value = "标准图", required = false)	private String standardPic;//标准图		@ApiModelProperty(value = "竖图", required = false)	private String ystandardPic;//竖图		@ApiModelProperty(value = "水印图片", required = false)  	private String markPic;//水印图片		@ApiModelProperty(value = "水印图片位置", required = false)	private String markPosition;//水印图片位置		@ApiModelProperty(value = "标签", required = false)	private String tag;//标签		@ApiModelProperty(value = "评分", required = false)	private String score;//评分		@ApiModelProperty(value = "描写叙述", required = false)	private String description;//描写叙述	public String getName() {		return name;	}	public void setName(String name) {		this.name = name;	}	public String getThirdAlbumId() {		return thirdAlbumId;	}	public void setThirdAlbumId(String thirdAlbumId) {		this.thirdAlbumId = thirdAlbumId;	}	public String getThirdSystemId() {		return thirdSystemId;	}	public void setThirdSystemId(String thirdSystemId) {		this.thirdSystemId = thirdSystemId;	}	public String getStandardPic() {		return standardPic;	}	public void setStandardPic(String standardPic) {		this.standardPic = standardPic;	}	public String getYstandardPic() {		return ystandardPic;	}	public void setYstandardPic(String ystandardPic) {		this.ystandardPic = ystandardPic;	}	public String getMarkPic() {		return markPic;	}	public void setMarkPic(String markPic) {		this.markPic = markPic;	}	public String getMarkPosition() {		return markPosition;	}	public void setMarkPosition(String markPosition) {		this.markPosition = markPosition;	}	public String getTag() {		return tag;	}	public void setTag(String tag) {		this.tag = tag;	}	public String getScore() {		return score;	}	public void setScore(String score) {		this.score = score;	}	public String getDescription() {		return description;	}	public void setDescription(String description) {		this.description = description;	}	}

返回參数。这里也是用的实体

package com.gochina.mis.vo;import java.sql.Timestamp;import com.wordnik.swagger.annotations.ApiModelProperty;/** * 返回信息 * @author LBQ-PC * */public class BaseVo {	/**	 * 状态	 */	@ApiModelProperty(value = "状态") 	private Boolean success;		/**	 * 消息	 */	@ApiModelProperty(value = "消息")	private String msg;		/**	 * server当前时间	 */	@ApiModelProperty(value = "server当前时间戳，sample： 1434553831")	private Long currentTime = new Timestamp(System.currentTimeMillis()).getTime();	public Boolean getSuccess() {		return success;	}	public void setSuccess(Boolean success) {		this.success = success;	}	public String getMsg() {		return msg;	}	public void setMsg(String message) {		this.msg = message;	}	public Long getCurrentTime() {		return currentTime;	}	public void setCurrentTime(Long currentTime) {		this.currentTime = currentTime;	}}

执行訪问：http://localhost:8080/api-doc/index.html ，当然，我们也能够对这个页面加权限验证

大功告成！对于开发者来说，每一个接口仅仅须要加入一些注解，SwaggerUI会自己主动生成如我们文章開始时展现的页面，方便调用和測试。