Spring MVC 中使用 Swagger2 构建动态 RESTful API
当多终端(WEB/移动端)需要公用业务逻辑时,一般会构建 RESTful 风格的服务提供给多终端使用。
为了减少与对应终端开发团队频繁沟通成本,刚开始我们会创建一份 RESTful API 文档来记录所有接口细节。
但随着项目推进,这样做所暴露出来的问题也越来越严重。
a. 接口众多,细节复杂(需考虑不同的 HTTP 请求类型、HTTP 头部信息、HTTP 请求内容..),高质量地创建这份文档本身就是件非常吃力的事。
b. 不断修改接口实现必须同步修改接口文档,而文档与代码又处于两个不同的媒介,除非有严格的管理机制,不然很容易导致不一致现象。
基于此,项目组在早些时间引入了 Swagger,经过几个项目的沉淀,确实起到了很不错的效果。
Swagger 是一个规范和完整的框架,用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。
服务的方法、参数、模型紧密集成到服务器端的代码,让维护文档和调整代码融为一体,使 API 始终保持同步。
本文主要描述 Swagger 与 SpringMVC 的集成过程以及遇到的一些问题,权当抛砖引玉只用,具体项目具体分析。
1. Maven 依赖和最简配置
<!--restfull APi swagger2-->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>${swagger.version}</version>
</dependency> <dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>${swagger.version}</version>
</dependency>
Spring-Context Swagger 配置:
<!-- swagger2 配置类-->
<bean id="config" class="com.rambo.spm.core.config.SwaggerConfig"/> <!-- swagger2 静态资源交由 spring 管理映射(springfox-swagger-ui.jar 为静态资源包)-->
<mvc:resources mapping="swagger-ui.html" location="classpath:/META-INF/resources/"/>
<mvc:resources mapping="/webjars/**" location="classpath:/META-INF/resources/webjars/"/>
<mvc:resources /> 由 Spring MVC 处理静态资源,并添加一些有用的附加值功能。
a. <mvc:resources /> 允许静态资源放在任何地方,如 WEB-INF 目录下、类路径下等,完全打破了静态资源只能放在 Web 容器的根路径下这个限制。
b.<mvc:resources /> 依据当前著名的 Page Speed、YSlow 等浏览器优化原则对静态资源提供优化。
SwaggerConfig 配置类:
@Configuration
@EnableSwagger2
public class SwaggerConfig {
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
.paths(PathSelectors.any())
.build();
}
private ApiInfo apiInfo() {
ApiInfoBuilder apiInfoBuilder = new ApiInfoBuilder();
apiInfoBuilder.title("SPM Doc");
apiInfoBuilder.description("SPM Api文档");
apiInfoBuilder.contact(new Contact("orson", "https://www.cnblogs.com/", ""));
apiInfoBuilder.version("2.0");
return apiInfoBuilder.build();
}
}
对于生成哪些请求方法 API ? Swagger 提供了 RequestHandlerSelectors 对象的以下方法进行限制范围:
2. 服务注解配置实践
经过上述的操作,其实 Swagger 已经集成完毕,在项目开发推进中,只需在对应 RESTful 服务上添加对应注解即可。
@Api:注解在类上,说明该类的作用。可以标记一个 Controller 类做为 swagger 文档资源,使用方式:
@Api(description = "用户管理")
@ApiOperation:注解在方法上,说明方法的作用,每一个url资源的定义,使用方式:
@ApiOperation(value = "获取所有用户列表")
@ApiParam、@ApiImplicitParam:注解到参数上,说明该参数作用,使用方式:
@ApiParam(value = "用户ID") String userId
上述都为最简配置,构建清晰的 API 文档已足够,当然还有很丰富的注解,知道有就行了。
@RestController
@Api(description = "用户管理")
public class UserRestController extends BaseController {
@Autowired
private SysUserService sysUserService; @GetMapping("r/user/get")
@ApiOperation(value = "获取特定用户详情")
public Object getUser(ModelMap modelMap, @ApiParam(value = "用户ID") String userId) { } @PostMapping("r/user/add")
@ApiOperation(value = "添加用户")
public Object addUser(ModelMap modelMap, @ModelAttribute @Valid SysUser user, BindingResult result) { }
}
在项目后续使用中遇到的一些问题:
a. 一些方法入参如 HttpServletRequest、HttpServletResponse、HttpSession、ModelMap 等等,这些参数在生成 API 文档时是无意义的,Swagger 正确的配置方式?
刚开始时使用 @ApiParam(hidden = true) 注解这些参数,方法繁多的时候,这些类型的入参都要写一遍,使用起来很冗余。
在 API 中发现 Docket 对象有 ignoredParameterTypes 方法,在配置类中统一定义忽略的参数类型即可,这样就方便很多。
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.ignoredParameterTypes(ModelMap.class, HttpServletRequest.class,HttpServletResponse.class, BindingResult.class)
.select()
.apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
.paths(PathSelectors.any())
.build();
}
b. 当请求的参数为封装的对象时,怎样进行注解?对象中的属性怎样注解?怎样屏蔽对象中的莫个属性?
请求的参数为对象时,使用Spring @ModelAttribute 注解对应对象,对象当中的属性使用 @ApiModelProperty ,屏蔽莫个属性 @ApiModelProperty(hidden = true)
@ApiModelProperty(hidden = true)
private String uuid; @ApiModelProperty("姓名")
private String name; @ApiModelProperty("密码")
private String passwd;
c. @Api 注解中的 tags 值不支持中文,中文值会导致无法展开;
Swagger 有很丰富的工具,还能做很多事,本文所述只是能让你迅速了解它、使用它、有需要多查资料、多翻博客。
Spring MVC 中使用 Swagger2 构建动态 RESTful API的更多相关文章
- Spring MVC中使用 Swagger2 构建Restful API
1.Spring MVC配置文件中的配置 [java] view plain copy <!-- 设置使用注解的类所在的jar包,只加载controller类 --> <contex ...
- Spring Boot中使用Swagger2构建强大的RESTful API文档
由于Spring Boot能够快速开发.便捷部署等特性,相信有很大一部分Spring Boot的用户会用来构建RESTful API.而我们构建RESTful API的目的通常都是由于多终端的原因,这 ...
- Spring Boot中使用Swagger2构建RESTful API文档
在开发rest api的时候,为了减少与其他团队平时开发期间的频繁沟通成本,传统做法我们会创建一份RESTful API文档来记录所有接口细节,然而这样的做法有以下几个问题: 1.由于接口众多,并且细 ...
- Spring Boot 中使用 Swagger2 构建强大的 RESTful API 文档
项目现状:由于前后端分离,没有很好的前后端合作工具. 由于接口众多,并且细节复杂(需要考虑不同的HTTP请求类型.HTTP头部信息.HTTP请求内容等),高质量地创建这份文档本身就是件非常吃力的事,下 ...
- Spring Boot中使用Swagger2构建RESTful APIs
关于 Swagger Swagger能成为最受欢迎的REST APIs文档生成工具之一,有以下几个原因: Swagger 可以生成一个具有互动性的API控制台,开发者可以用来快速学习和尝试API. S ...
- Spring Boot中使用Swagger2构建RESTful APIs介绍
1.添加相关依赖 <!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 --> <depen ...
- Spring Boot中使用Swagger2构建API文档
程序员都很希望别人能写技术文档,自己却很不愿意写文档.因为接口数量繁多,并且充满业务细节,写文档需要花大量的时间去处理格式排版,代码修改后还需要同步修改文档,经常因为项目时间紧等原因导致文档滞后于代码 ...
- Spring Boot中使用Swagger2构建强大的RESTful(最新全,无坑)
1:说明 网上这类文章 太多, 一搜一大把 ,但是要不是知识太过于老旧,就是配置没有说名清楚,你的项目按照他的配置却不能正常运行: 所以本文的目的: 配置swagger 2 那swagger 1 不 ...
- Spring Boot中使用Swagger2自动构建API文档
由于Spring Boot能够快速开发.便捷部署等特性,相信有很大一部分Spring Boot的用户会用来构建RESTful API.而我们构建RESTful API的目的通常都是由于多终端的原因,这 ...
随机推荐
- php数组和正则表达式的替换拆分匹配所有
正则表达式 $s = "a1s2d3f1g5f";//echo preg_replace("/\d/","#",$s); //替换 //$ ...
- XP和win7的软件崩溃提示
运行在XP上的应用软件崩溃时总提示:应用程序错误,xxxxx地址不能写... 现在win7上提示的就只有关闭和调试程序,没有这些详细信息.其实win7下面也记录了相关的信息. 位置在:“控制面板” - ...
- Linux环境下安装禅道
1.下载禅道包 http://dl.cnezsoft.com/zentao/7.3/ZenTaoPMS.7.3.stable.zbox_64.tar.gz http://dl.cnezsoft.c ...
- [js高手之路]面向对象+设计模式+继承一步步改造简单的四则运算
到目前为止,我已经写完了面向对象完整的一个系列知识,前面基本属于理论,原理的理解,接下来,我们就用学到的知识来实战下吧. 看看理解原理和理论是否重要?例子从简单到复杂 一.单体(字面量)封装加减乘除 ...
- win7系统中如何使文件显示出扩展名或显示文件后缀名
win7系统中如何使文件显示出扩展名-------------------- 1.点击计算机-->>点击组织,然后选择“文件夹及搜索选项”-->> -------------- ...
- PYQT4 : QSystemTrayIcon练习
照着demo自己做了一遍,练练手 import sys from PyQt4 import QtGui from PyQt4 import QtCore class SysTray(QtGui.QDi ...
- Struts2-文件上传下载
Struts2文件上传 提供 FileUpload 拦截器,用于解析 multipart/form-data 编码格式请求,解析上传文件的内容 fileUpload拦截器 默认在 defaultSta ...
- ubuntu下安装rubymine
1.安装jdk 先查看系统有没有安装jdk,打开终端,输入以下命令: java -version 如果没有安装,在联网的环境下执行: $ -jdk 2.安装rubymine 从官网(http://ww ...
- anaconda安装加速镜像问题解决
Anaconda使用conda连接网络出现错误 我使用的是windows10 64bit下的Anaconda2,在安装和更新包的时候出现以下报错信息. 这是使用默认源安装包的报错信息: C:Users ...
- jenkins 配置qq邮箱