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/"/>
a. b. 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 正确的配置方式? 刚开始时使用 在 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) private String uuid; @ApiModelProperty("姓名") private String name; @ApiModelProperty("密码") private String passwd; Swagger 有很丰富的工具,还能做很多事,本文所述只是能让你迅速了解它、使用它、有需要多查资料、多翻博客。 总结 以上就是这篇文章的全部内容了,本文还有许多不足,希望本文的内容对大家的学习或者工作具有一定的参考学习价值,如果有疑问大家可以留言交流,谢谢大家对编程小技巧的支持。 (编辑:李大同) 【声明】本站内容均来自网络,其相关言论仅代表作者个人观点,不代表本站立场。若无意侵犯到您的权利,请及时与联系站长删除相关内容! |