分享一个集成在项目中的REST APIs文档框架swagger
1 为什么是使用swagger?
1-1 当后台开发人员开发好接口,是不是还要重新书写一份接口文档提给前端人员,当然对于程序员最不喜欢的就是书写文档(当然文档是必须的,有利于项目的维护)
1-2 当后台人员开发接口,当然后台开发者也是需要测试好接口是否可用,当参数少的时候测试还不是很麻烦,当参数有十多个的时候,就需要后台开发者一个一个的拼接参数,很是耗时间而且还容易写错参数名,swagger就很好解决了这个问题(当然也是可以借助其他插件:rest-client工具,PostMan)
2 搭建环境:window,spring boot,swaager,maven
3 开始搭建:搭建过程很简单,有关于swagger注解本文不详细叙述,其实只使用常用的几个注解就ok了(@ApiOperation,@EnableSwagger2,@Api)
3-1 导入必须jar包 ,修改pom.xml
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-test</artifactId>
<scope>test</scope>
</dependency>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-web</artifactId>
<version>RELEASE</version>
</dependency> <dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-aop</artifactId>
</dependency> <!-- swagger -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version> 2.6.0</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version> 2.6.0</version>
</dependency>
<!-- swagger end -->
3-2 配置swagger
@Configuration
@EnableSwagger2 //swagger注解
public class SwaggerConfig { @Bean
public Docket allInterface() {
return new Docket(DocumentationType.SWAGGER_2).groupName("AllInterface(所有接口)")// 定义组
.select() // 选择那些路径和api会生成document
.apis(RequestHandlerSelectors.basePackage("com.lishun.controller")) // 拦截的包路径
.paths(regex("/.*"))// 拦截的接口路径
.build() // 创建
.apiInfo(apiInfo())// 配置说明
.tags(new Tag("index", "起始页"), getTags());
}
/**
* @Description:这里可以指定其他tag(对应controller的@Api注解的tags属性值)
* @author lishun
* @date 2018/2/28
* @param []
* @return springfox.documentation.service.Tag[]
*/
private Tag[] getTags() {
Tag[] tags = { new Tag("login", "登录相关") };
return tags;
} private ApiInfo apiInfo() {
return new ApiInfoBuilder()//
.title("swagger api 文档")// 标题
.description("swagger api 文档")// 描述
.termsOfServiceUrl("")//
.contact(new Contact("", "", ""))// 联系
.version("1.0")// 版本
.build();
}
}
3-3 统一所有接口返回值(便于前端人员开发,和统一处理controller异常)
public class ResultBean<T> implements Serializable {
/*提示信息*/
public String message = "";
/*状态码*/
public Integer code;
/*总页数*/
private long totalPage;
/*页容量*/
private int pages;
/*页码*/
private int pageNum;
/*返回实体信息*/
private T resultData;
/*返回集合实体信息*/
private List<T> resultDataList; public ResultBean() {
} public ResultBean(List<T> resultData, long totalPage, int pages, int pageNum) {
this.resultDataList = resultData;
this.totalPage = totalPage;
this.pages = pages;
this.pageNum = pageNum;
} public ResultBean(T resultData) {
this.resultData = resultData;
} public void setMessage(String message) {
this.message = message;
} public long getTotalPage() {
return totalPage;
} public void setTotalPage(long totalPage) {
this.totalPage = totalPage;
} public int getPages() {
return pages;
} public void setPages(int pages) {
this.pages = pages;
} public int getPageNum() {
return pageNum;
} public void setPageNum(int pageNum) {
this.pageNum = pageNum;
} public List<T> getResultDataList() {
return resultDataList;
} public void setResultDataList(List<T> resultDataList) {
this.resultDataList = resultDataList;
} public void setMessage(String message, Object... args) {
this.message = String.format(message, args);
} public String getMessage() {
return message;
} public void setResultData(T resultData) {
this.resultData = resultData;
} public T getResultData() {
return this.resultData;
} public Integer getCode() {
return code;
} public void setCode(Integer code) {
this.code = code;
} public <T> void setResultBean(Integer code, String message,
Object... mesaageFormatArgs) {
setCode(code);
setMessage(message, mesaageFormatArgs);
}
}
3-4 统一处理controller异常
/**
* @author lishun
* @Description: 控制器aop拦截
* @date 2017/10/27
*/
@Component
@Aspect
public class ControllerAspect {
@Pointcut("execution(public com.lishun.result.ResultBean com.lishun.controller.*.*(..))")
public void dataSource(){}; @Around("dataSource()")
public Object doAround(ProceedingJoinPoint proceedingJoinPoint) throws Throwable {
ResultBean result = null;
try {
result = (ResultBean<?>)proceedingJoinPoint.proceed();
} catch (Exception e) {
result = new ResultBean();
result.setCode(ResultCode.FAILED);
result.setMessage(e.getMessage());
e.printStackTrace();
}
return result;
}
}
3-4 contrlloer
@RestController
@Api(tags = { "index" })
public class IndexController { @GetMapping("/index/{id}")
@ApiOperation(value = "findByOne", notes = "获取一条数据")
public ResultBean<String> findByOne(@PathVariable(value = "id") String id) {
ResultBean<String> resultBean = new ResultBean<>();
resultBean.setCode(ResultCode.OK);
resultBean.setResultData("请求成功");
return resultBean;
}
@PostMapping("/index/add")
@ApiOperation(value = "add", notes = "新增")
public ResultBean<String> add(Users users) {
ResultBean<String> resultBean = new ResultBean<>();
resultBean.setCode(ResultCode.OK);
resultBean.setResultData("请求成功");
return resultBean;
}
@DeleteMapping("/index/delete/{id}")
@ApiOperation(value = "delete", notes = "删除")
public ResultBean<String> delete(@PathVariable(value = "id") String id) {
ResultBean<String> resultBean = new ResultBean<>();
resultBean.setCode(ResultCode.OK);
resultBean.setResultData("请求成功");
return resultBean;
}
}
3-5 测试
主要是测试接口api,所以这里就没有数据库访问的业务逻辑层
启动项目,访问http://localhost:8080/swagger-ui.html#/
展开add接口
3-6 注意!!!!! 生成环境需要把swagger禁用,swagger只是适合在开发和测试环境中使用,源代码
分享一个集成在项目中的REST APIs文档框架swagger的更多相关文章
- 使用Swagger2构建SpringMVC项目中的Restful API文档
使用Swagger自动生成API文档,不仅增加了项目的可维护性,还提高了API的透明度更利于快速测试等工作,便于更快地发现和解决问题. 本篇文章只记录整合过程,关于Security Configura ...
- 分享我在 vue 项目中关于 api 请求的一些实现及项目框架
本文主要简单分享以下四点 如何使用 axios 如何隔离配置 如何模拟数据 分享自己的项目框架 本文主要目的为以下三点 希望能够帮到一些人 希望能够得到一些建议 奉上一个使用Vue的模板框架 我只是把 ...
- .NET平台开源项目速览(4).NET文档生成工具ADB及使用
很久以前就使用ADB这个工具来生成项目的帮助文档.功能强大,在学习一些开源项目的过程中,官方没有提供CHM帮助文档,所以为了快速的了解项目结构和注释.就生成文档来自己看,非常好用.这也是一个学习方法吧 ...
- API文档工具-Swagger的集成
最近安装了API文档工具swagger,因为Github上已有详细安装教程,且安装过程中没有碰到大的阻碍,所以此文仅对这次安装做一份大致记录 相关网站 Swagger 官方地址: http://swa ...
- 如何在ASP.NET Core 中快速构建PDF文档
比如我们需要ASP.NET Core 中需要通过PDF来进行某些简单的报表开发,随着这并不难,但还是会手忙脚乱的去搜索一些资料,那么恭喜您,这篇帖子会帮助到您,我们就不会再去浪费一些宝贵的时间. 在本 ...
- Springboot中整合knife4j接口文档
在项目开发过程中,web项目的前后端分离开发,APP开发,需要由前端后端工程师共同定义接口,编写接口文档,之后大家都根据这个接口文档进行开发. 什么是knife4j 简单说knife4j就swagge ...
- 在我的电脑中删除wps云文档图标
在我的电脑中删除wps云文档图标 右键点击win10左下角选择运行,输入regedit打开注册表后,找到以下注册表路径: HKEY_CURRENT_USER\Software\Microsoft\Wi ...
- 分享一个集成.NET Core+Swagger+Consul+Polly+Ocelot+IdentityServer4+Exceptionless+Apollo+SkyWalking的微服务开发框架
集成.NET Core+Swagger+Consul+Polly+Ocelot+IdentityServer4+Exceptionless+Apollo的微服务开发框架 Github源代码地址 htt ...
- 分享一个CQRS/ES架构中基于写文件的EventStore的设计思路
最近打算用C#实现一个基于文件的EventStore. 什么是EventStore 关于什么是EventStore,如果还不清楚的朋友可以去了解下CQRS/Event Sourcing这种架构,我博客 ...
随机推荐
- JavaScript总结学习一:js中构造函数与普通函数的区别
构造函数不仅只出现在JavaScript中,它同样存在于很多主流的程序语言里,比如c++.Java.PHP等等.与这些主流程序语言一样,构造函数在js中的作业一样,也是用来创建对象时初始化对象,并且总 ...
- 以守护进程的方式部署flask
1.文件目录 创建一个简单的flask 项目... application = Flask(__name__) application.debug = True 2.安装wsgi pip instal ...
- node.js核心模块
全局对象 global 是全局变量的宿主 全局变量 在最外层定义的 全局对象的属性 隐士定义的变量(未定义直接赋值的变量) 当定义一个全局变量时 这个变量同时也会成为全局对象的属性 反之亦然 注意: ...
- js_3_for_if_try
在js中有哪些特殊变量? null 指向一个空地址,一个特殊的地址 var u 定义了一个特殊变量u,类型未定义,boolean(u)=false js中的for循环是什么样子? 对列表: for(v ...
- Java客户端工具选择:HTML?Swing?XML?
整理下面的文章是因为个人觉得写的很好,关于java的客户端了解也并不是太多.看了下面的文章觉得很有必要贴出来,方便自己以后了解java客户端编程. Java软件设计师和管理人员经常会面临这样的难题:在 ...
- jsp中 scope="application" 表示
jsp中 <jsp:useBean id="countbean" scope="application" class="count.counte ...
- 【视频编解码·学习笔记】4. H.264的码流封装格式
一.码流封装格式简单介绍: H.264的语法元素进行编码后,生成的输出数据都封装为NAL Unit进行传递,多个NAL Unit的数据组合在一起形成总的输出码流.对于不同的应用场景,NAL规定了一种通 ...
- HTTP请求和MIME介绍
HTTP请求和MIME介绍 HTTP请求由三部分组成,分别是: 请求行,消息报头,请求正文. 请求行(格式): Method Request-URI HTTP-Version CRLF Method: ...
- cordova+vue 项目打包成Android(apk)应用
现在使用vue开发的项目越来越多,使用vue开发的移动端打包就成了最大的问题.现在前端打包方案有好多种,但是综合来说,我比较喜欢用cordova来进行Android和ios的打包,配置完成之后,每次只 ...
- 关于dom4j解析xml
一:相关jar包 dom4j-1.6.1.jar 二:用例xml文件 三:解析 注:可能有的小白不知道如果获取节点,so,you can: for (Iterator<Element> i ...