SwaggerUI+SpringMVC——构建RestFulAPI的可视化界面
来源:互联网 发布:unity3d 绘画涂鸦 编辑:程序博客网 时间:2024/05/17 10:41
今天给大家介绍一款工具,这个工具目前可预见的好处是:自动维护最新的接口文档。
我们都知道,接口文档是非常重要的,但是随着代码的不断更新,文档却很难持续跟着更新,今天要介绍的工具,完美的解决了这个问题。而且,对于要使用我们接口的人来说,不需要在给他提供文档,告诉他地址,一目了然。
最近项目中一直有跟接口打交道,恰好又接触到了一个新的接口工具,拿出来跟大家分享一下。
关于REST接口,我在上篇文章中已经有介绍,这里来说一下如何配合SwaggerUI搭建RestFul API 的可视化界面。最终要达到的效果是这样的:
它可以支持Rest的所有提交方式,如POST,GET,PUT,DELETE等。
这里可以看到我们的方法注释,需要的参数,参数的类型和注释,返回值的类型注释等信息,最重要的,我们这里可以直接对REST接口测试。
接下来,我们一起开始逐步实现如图的效果
第一步:首先,引入依赖的jar包
下载swagger-ui
https://github.com/swagger-api/swagger-ui
将dist下的文件放入webapp下
配置mvc:resource,防止spring拦截。
http://petstore.swagger.wordnik.com/v2/swagger.json
修改为http://localhost:8080/{projectname}/api-docs
到此,完成了所有的基本配置,接下来,需要对每个接口添加注解。
下面来个实例
接口类
请求参数实体
大功告成!对于开发人员来说,每个接口只需要添加一些注解,SwaggerUI会自动生成如我们文章开始时展现的页面,方便调用和测试。
版权声明:本文为博主原创文章,未经博主允许不得转载。
我们都知道,接口文档是非常重要的,但是随着代码的不断更新,文档却很难持续跟着更新,今天要介绍的工具,完美的解决了这个问题。而且,对于要使用我们接口的人来说,不需要在给他提供文档,告诉他地址,一目了然。
最近项目中一直有跟接口打交道,恰好又接触到了一个新的接口工具,拿出来跟大家分享一下。
关于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@EnableSwaggerpublic class SwaggerConfig {private SpringSwaggerConfig springSwaggerConfig;@Autowiredpublic 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;@Controllerpublic class AlbumAction {private static Logger logger = LoggerFactory.getLogger(AlbumAction.class);@Autowiredprivate 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会自动生成如我们文章开始时展现的页面,方便调用和测试。
版权声明:本文为博主原创文章,未经博主允许不得转载。
0 0
- SwaggerUI+SpringMVC——构建RestFulAPI的可视化界面
- SwaggerUI+SpringMVC——构建RestFulAPI的可视化界面
- [ RESP-API ] SwaggerUI+SpringMVC——构建RestFulAPI的可视化界面
- SwaggerUI+SpringMVC——构建RestFul API的可视化界面
- SwaggerUI+SpringMVC-构建RestFul API的可视化界面
- 【MongoDB】——可视化界面
- [java]构建在线restfulAPI文档之swagger2
- Oracle数据库的可视化界面
- 关于项目管理的一点体会——需求等级、任务分解、可视化、每日构建
- 一个以可视化界面的方式管理与调度Hadoop的作业平台——Zeus
- 使用GMF开发可视化界面编辑器(三)——连接线的绘制
- 使用GMF开发可视化界面编辑器(五)——模型的约束校验
- 构建灵活的界面
- 使用apache的HTTPclient访问restfulAPI
- SpringMVC拓展——利用maven构建springMVC项目
- 致歉 —— 关于《WINX如何做到可视化界面开发》
- 使用GMF开发可视化界面编辑器(四)——Compartment
- 构建vim的可视化C++编辑平台
- Remove Duplicates from Sorted Array 删除中的重复元素
- 优秀的Android CSDN学习博客
- 运动目标检测--帧间差分与背景差分相融合
- spring security (五)Filter
- Monkey
- SwaggerUI+SpringMVC——构建RestFulAPI的可视化界面
- 网站构建 初级教程
- Git 总结
- vim中批量注释与解注释python代码
- Velocity 学习笔记
- Exchange 2010 PS 之New-distributionGroup&New-DynamicDistributionGroup!
- 小记 activity跳转附加动画效果
- Bootstrap标签页插件
- 铁血论坛v4.0官方iPhone版