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


本文转自Orson博客园博客,原文链接:http://www.cnblogs.com/java-class/p/7544610.html,如需转载请自行联系原作者

相关文章
|
10天前
|
IDE Java API
使用Java Web技术构建RESTful API的实践指南
使用Java Web技术构建RESTful API的实践指南
|
28天前
|
消息中间件 NoSQL Java
Redis Streams在Spring Boot中的应用:构建可靠的消息队列解决方案【redis实战 二】
Redis Streams在Spring Boot中的应用:构建可靠的消息队列解决方案【redis实战 二】
46 1
|
25天前
|
Web App开发 JavaScript NoSQL
深入浅出:构建基于Node.js的RESTful API
在当今快速发展的互联网时代,RESTful API已成为前后端分离架构中不可或缺的一部分。本文旨在为初学者和中级开发人员提供一个清晰、简洁的指南,详细介绍如何使用Node.js构建一个高效、可维护的RESTful API。通过结合实际案例,本文将从API设计理念出发,深入讲解如何利用Express框架及MongoDB数据库实现API的增删改查功能,同时探讨如何通过JWT进行安全认证,确保数据传输的安全性。此外,文章还将简要介绍如何使用Swagger生成API文档,使得API的测试和维护更加便捷。无论你是希望提升现有项目的API设计,还是想从零开始构建一个新项目,本文都将为你提供一条清晰的道路
|
4天前
|
API 开发者 UED
深入理解RESTful API设计原则
【2月更文挑战第9天】 传统的RESTful API设计原则在实际开发中并不是一成不变的,随着技术的发展和应用场景的变化,我们需要不断深入理解RESTful API的设计原则,并结合具体情况进行灵活应用,以更好地满足现代应用的需求。
12 4
|
7天前
|
API 网络架构
解释 RESTful API,以及如何使用它构建 web 应用程序。
解释 RESTful API,以及如何使用它构建 web 应用程序。
12 0
|
13天前
|
监控 Java API
如何动态通过API的形式在XxlJob上创建任务
如何动态通过API的形式在XxlJob上创建任务
11 0
|
17天前
|
缓存 Rust 安全
Rust中的RESTful API构建:实践与探索
本文详细阐述了在Rust编程语言中如何构建RESTful API的过程。我们将通过实际示例,介绍Rust的生态系统中用于构建API的流行库和框架,包括Actix-Web、Rocket和Gotham。此外,我们还将讨论RESTful设计原则、API安全性、性能优化等方面的内容,帮助读者在Rust中高效、安全地构建RESTful API。
|
24天前
|
存储 缓存 API
深入理解与实践RESTful API设计
在数字化时代,RESTful API已成为应用程序之间交互的重要桥梁。本文旨在提供一个全面的指南,从RESTful API的基本概念入手,深入探讨其设计原则、最佳实践以及常见的挑战。不同于一般的技术文章仅停留在表面的介绍,我们将结合实际案例,逐步分析如何设计一个既符合REST原则又能满足现代应用需求的API。通过本文,读者不仅能够掌握RESTful API的理论知识,更能学会如何在实际项目中灵活应用,从而提升整个系统的可扩展性和维护性。
|
25天前
|
缓存 安全 API
深入理解Web开发中的RESTful API设计
在当今快速演进的技术世界中,RESTful API已成为构建现代Web应用不可或缺的一部分。它不仅促进了前后端的分离发展,还为不同平台间的数据交换提供了一种高效、标准化的方式。本文旨在深入探讨RESTful API的设计原则和最佳实践,通过具体示例说明如何设计易于维护、可扩展和安全的API。我们将从REST的基本概念出发,逐步深入到资源命名、HTTP方法的恰当使用、状态码的选择、以及安全性考虑等方面,为读者提供一个全面而深入的视角,帮助大家更好地理解和运用RESTful API。
|
28天前
|
存储 NoSQL 关系型数据库
轻松打卡:使用Spring Boot和Redis Bitmap构建高效签到系统【redis实战 四】
轻松打卡:使用Spring Boot和Redis Bitmap构建高效签到系统【redis实战 四】
36 0

热门文章

最新文章

相关产品

  • 云迁移中心