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 有很丰富的工具，还能做很多事，本文所述只是能让你迅速了解它、使用它、有需要多查资料、多翻博客。

总结

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