Spring MVC利用Swagger2如何构建动态RESTful API详解

前言

本文主要给大家介绍了关于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;

Swagger 有很丰富的工具,还能做很多事,本文所述只是能让你迅速了解它、使用它、有需要多查资料、多翻博客。

总结

以上就是这篇文章的全部内容了,本文还有许多不足,希望本文的内容对大家的学习或者工作具有一定的参考学习价值,如果有疑问大家可以留言交流,谢谢大家对编程小技巧的支持。

版权声明:本文内容由互联网用户自发贡献,该文观点与技术仅代表作者本人。本站仅提供信息存储空间服务,不拥有所有权,不承担相关法律责任。如发现本站有涉嫌侵权/违法违规的内容, 请发送邮件至 dio@foxmail.com 举报,一经查实,本站将立刻删除。

相关推荐


本文从从Bitcask存储模型讲起,谈轻量级KV系统设计与实现。从来没有最好的K-V系统,只有最适合应用业务实际场景的系统,做任何的方案选择,要结合业务当前的实际情况综合权衡,有所取有所舍。
内部的放到gitlab pages的博客,需要统计PV,不蒜子不能准确统计,原因在于gitlab的host设置了strict-origin-when-cross-origin, 导致不蒜子不能正确获取referer,从而PV只能统计到网站的PV。 为了方便统计页面的PV,这里简单的写了一个java程
PCM 自然界中的声音非常复杂,波形极其复杂,通常我们采用的是脉冲代码调制编码,即PCM编码。PCM通过抽样、量化、编码三个步骤将连续变化的模拟信号转换为数字编码。 采样率 采样频率,也称为采样速度或者采样率,定义了每秒从连续信号中提取并组成离散信号的采样个数,它用赫兹(Hz)来表示。采样频率的倒数
本文介绍如何离线生成sst并在线加载,提供一种用rocksdb建立分布式kv系统替换mongodb的思路
验证用户输入是否正确是我们应用程序中的常见功能。Spring提供了`@Valid`和@`Validated`两个注解来实现验证功能,本文详细介绍 [@Valid]和[@Validated]注解的区别 。
引入pdf2dom &lt;dependency&gt; &lt;groupId&gt;net.sf.cssbox&lt;/groupId&gt; &lt;artifactId&gt;pdf2dom&lt;/artifactId&gt; &lt;version&gt;1.8&lt;/version&
grafana 是一款非常优秀的可视化报表工具,有设计精良的可视化工具,今天来聊一聊如何将grafana集成到自己的应用中。 原理是: grafana允许iframe访问,开启auth.proxy, java 后端鉴权后代理grafana 前端通过iframe访问后端代理过的grafana graf
介绍 Call Graph是一款IDEA插件,用于可视化基于IntelliJ平台的IDE的函数调用图。 这个插件的目标是让代码更容易理解,有助于读懂和调试代码。当前只支持Java。针对Typescript、Javascript或Python工具,可以使用作者的另外一款工具Codemap(https:
原理 通过线程安全findAndModify 实现锁 实现 定义锁存储对象: /** * mongodb 分布式锁 */ @Data @NoArgsConstructor @AllArgsConstructor @Document(collection = &quot;distributed-loc
Singleton 单例模式 单例模式是确保每个应用程序只存在一个实例的机制。默认情况下,Spring将所有bean创建为单例。 你用@Autowired获取的bean,全局唯一。 @RestController public class LibraryController { @Autowired
pipeline 分布式任务调度器 目标: 基于docker的布式任务调度器, 比quartzs,xxl-job 更强大的分布式任务调度器。 可以将要执行的任务打包为docker镜像,或者选择已有镜像,自定义脚本程序,通过pipeline框架来实现调度。 开源地址: https://github.c
python训练的模型,转换为onnx模型后,用python代码可以方便进行推理,但是java代码如何实现呢? 首先ONNX 推理,可以使用`onnxruntime` ```xml com.microsoft.onnxruntime onnxruntime 1.15.1 ``` 另外,训练的模型需要
要获取内网地址,可以尝试连接到10.255.255.255:1。如果连接成功,获取本地套接字的地址信息就是当前的内网IP。 python实现: ```python import socket def extract_ip(): st = socket.socket(socket.AF_INET, s
为什么要有索引 gremlin 其实是一个逐级过滤的运行机制,比如下面的一个简单的gremlin查询语句: g.V().hasLabel(&quot;label&quot;).has(&quot;prop&quot;,&quot;value&quot;) 运行原理就是: 找出所有的顶点V 然后过滤出
最近在分析一个应用中的某个接口的耗时情况时,发现一个看起来极其普通的对象创建操作,竟然每次需要消耗 8ms 左右时间,分析后发现这个对象可以通过对象池模式进行优化,优化后此步耗时仅有 0.01ms。
点赞再看,动力无限。Hello world : ) 微信搜「 程序猿阿朗 」。 本文 Github.com/niumoo/JavaNotes 和 未读代码网站 已经收录,有很多知识点和系列文章。 此篇文章介绍 Java JMX 技术的相关概念和具体的使用方式。 当前文章属于Java 性能分析优化系列
如何将Java JAR 转化为 win/mac/linux 独立可执行程序?不需要预装 JRE 运行?
点赞再看,动力无限。 微信搜「 程序猿阿朗 」。 本文 Github.com/niumoo/JavaNotes 和 未读代码博客 已经收录,有很多知识点和系列文章。 Java 19 在2022 年 9 月 20 日正式发布,Java 19 不是一个长期支持版本,直到 2023 年 3 月它将被 JD
点赞再看,动力无限。Hello world : ) 微信搜「 程序猿阿朗 」。 本文 Github.com/niumoo/JavaNotes 和 未读代码博客 已经收录,有很多知识点和系列文章。 前言 Java 反编译,一听可能觉得高深莫测,其实反编译并不是什么特别高级的操作,Java 对于 Cla
JSON 对于开发者并不陌生,如今的 WEB 服务、移动应用、甚至物联网大多都是以 **JSON** 作为数据交换的格式。学习 JSON 格式的操作工具对开发者来说是必不可少的。这篇文章将介绍如何使用 **Jackson** 开源工具库对 JSON 进行常见操作。