今天給大家介紹一款工具，這個工具眼下可預見的優點是：自己主動維護最新的接口文檔。
我們都知道，接口文檔是非常重要的，可是隨着代碼的不斷更新，文檔卻非常難持續跟着更新，今天要介紹的工具，完美的攻克了這個問題。
近期項目中一直有跟接口打交道，恰好又接觸到了一個新的接口工具，拿出來跟大家分享一下。
並且。對於要使用我們接口的人來說，不須要在給他提供文檔，告訴他地址。一目了然。
關於REST接口，我在上篇文章中已經有介紹。這里來說一下怎樣配合SwaggerUI搭建RestFul API 的可視化界面。終於要達到的效果是這種：
它能夠支持Rest的全部提交方式，如POST,GET,PUT,DELETE等。
這里能夠看到我們的方法凝視，須要的參數。參數的類型和凝視。返回值的類型凝視等信息，最重要的，我們這里能夠直接對REST接口測試。
接下來。我們一起開始逐步實現如圖的效果
第一步：首先。引入依賴的jar包
<span style="white-space:pre"> </span><!-- swagger -->
<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>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>
第二步，創建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
@EnableSwagger
public 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容器
<span style="white-space:pre"> </span><!--swagger--> <bean class="com.gochina.mis.util.SwaggerConfig"/>到這里，我們后台的環境代碼就完畢了，接着，加入SwaggerUI提供的js界面
下載swagger-ui
https://github.com/swagger-api/swagger-ui
將dist下的文件放入webapp下
配置mvc：resource。防止spring攔截。
https://github.com/swagger-api/swagger-ui
將dist下的文件放入webapp下
配置mvc：resource。防止spring攔截。
<span style="white-space:pre"> </span><mvc:resources mapping="/api-doc/**" location="/api-doc/" />將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;
@Controller
public 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會自己主動生成如我們文章開始時展現的頁面，方便調用和測試。