李保强 廊坊师范学院信息技术提高班 第八期

思想,让一个人变得无比强大!

SwaggerUI+SpringMVC——构建RestFul API的可视化界面
今天给大家介绍一款工具,这个工具目前可预见的好处是:自动维护最新的接口文档。
我们都知道,接口文档是非常重要的,但是随着代码的不断更新,文档却很难持续跟着更新,今天要介绍的工具,完美的解决了这个问题。而且,对于要使用我们接口的人来说,不需要在给他提供文档,告诉他地址,一目了然。
最近项目中一直有跟接口打交道,恰好又接触到了一个新的接口工具,拿出来跟大家分享一下。
关于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拦截。
<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;
	
	/**
	 * 服务器当前时间
	 */
	@ApiModelProperty(value = "服务器当前时间戳,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会自动生成如我们文章开始时展现的页面,方便调用和测试。


阅读更多
版权声明:本文为博主原创文章,未经博主允许不得转载。 https://blog.csdn.net/lbq613613/article/details/47398715
文章标签: SwaggerUI RESTFUL API
个人分类: SSH
想对作者说点什么? 我来说一句

没有更多推荐了,返回首页

不良信息举报

SwaggerUI+SpringMVC——构建RestFul API的可视化界面

最多只允许输入30个字

加入CSDN,享受更精准的内容推荐,与500万程序员共同成长!
关闭
关闭