分享一个集成在项目中的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这种架构,我博客 ...
随机推荐
- Powerdesigner+Execel
1.将Powerdesigner中的表(PDM)导入到execel中 Ctrl+Shift+X/tool->Execute commands ->Edit/Run script 粘贴如下v ...
- Selenium滚动条window.scrollTo和window.scrollBy
Selenium操作滚动条有两种方法,一种就是window.scrollTo,另一种是window.scrollBy,既然两个都可以用来操作滚动条,那这两个方法有什么区别呢? 1.window.scr ...
- 【转】查询SQLSERVER执行过的SQL记录
--创建时间 QS.creation_time, --查询语句 ), (( THEN DATALENGTH(st.text) ) ) AS statement_text, --执行文本 ST.text ...
- Discuz论坛URL静态化规则urlrewrite
http://blog.csdn.net/u014181418/article/details/53467980 1.在论坛代码目录下新建文件".htaccess" vim /us ...
- 一、Html简介
html什么东西呢? hypertext markup language(超文本标记语言).超级文本标记语言是标准通用标记语言下的一个应用,也是一种规范,一种标准, 它通过标记符号来标记要显示的网页中 ...
- Intel DPDK 全面解读
高性能网络技术 随着云计算产业的异军突起,网络技术的不断创新,越来越多的网络设备基础架构逐步向基于通用处理器平台的架构方向融合,从传统的物理网络到虚拟网络,从扁平化的网络结构到基于 SDN 分层的网络 ...
- tomcat无法打开8080页面
tomcat已启动 app已经正常执行 但不能打开8080管理页面 可能是在webapps目录下没有ROOT目录
- Sql Server的艺术(三) SQL聚合函数的应用
SQL提供的聚合函数有求和,最大值,最小值,平均值,计数函数等. 聚合函数及其功能: 函数名称 函数功能 SUM() 返回选取结果集中所有值的总和 MAX() 返回选取结果集中所有值的最大值 MIN( ...
- C#之DataTable转List与List转Datatable
闲来无事,只有写代码啦,以下为DataTable转List与List转DataTable的两个方法,主要技术点用到了反射原理: /// <summary> /// 模型转换类 /// &l ...
- 关于C#连接Oracle数据库 尝试加载Oracle客户端时引发BadImageFormatException 如果在安装32位Oracle客户端组件的情况下以64位模式运行,将出现此问题
这个问题已经困扰了我快一个月了,各种百度,各种博客,可是,一个个都试过了,什么下载32位客户端,配置环境变量什么的,纯属扯犊子,开发环境win10 64位 oracle 11g r2 64位,这 ...